Versions Compared

Old Version 1

changes.mady.by.user Marcus Brändle

Saved on

compared with

New Version 2

changes.mady.by.user Marcus Brändle

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Interface "Segmentations"

Status

Status
colourGreen
titleimplemented

Usage & contents

  • Metadata about the segmentations used in other interfaces (Valuations, Attributions, Contributions etc.)

  • Defines ordering and hierarchies of segmentations

Path

/segmentations

Parameters

reportingDate

string (date)

The date, the segmentations are valid

Example call

/segmentations?reportingDate=2019-03-31

Response structure

If the API can fulfill the request (response status code 200 = OK) the response must follow the below json-schema.

Note

  • The request part of the response has to match the path and parameters used in the API call/request

  • The json schema currently excludes the schemas for dataVersioning (should be designed by CSAM)

Schema

https://bitbucket.org/banknotes/ngr/src/df61b39d18a16581cd95aed9694991bbe39c5fb1/ngr-csamsolution/src/Model/schema/Segmentations.schema.json?at=release%2Fcurrent

Error handling

If the request can't be fulfilled an appropriate response status code (4xx or 5xx) must be used. Possible errors could be

  • bad request structure → expected status = 400

  • data not found or reportingDate in future → expected status = 404

  • etc.

The body of the response should contain information about the reason of the error in plain text or as json object.

Reporting business logic

  • aggregations, grouping, sorting, filtering along segmentations

Consistency rules

The following rules should be adhered to by any response and will eventually be checked when consuming a response:

Consistency Rules
Code Block
languagejs
* All segmentations used within the other API's should be defined
* All segments used within other API's responses should be defined
* All segments of a segmentation have to be unique

Segmentations don't have to be "levelled". That means that not every branch of a hierarchy has to have the same depth (number of levels).

Reporting business logic

  • aggregations, grouping, sorting, filtering along segmentations

Path

/segmentations

Parameters

reportingDate

string (date)

The date, the segmentations are valid

Example call

/segmentations?reportingDate=2019-03-31

Schema

Status
titleon request

Example

Status
titleon request

Segmentations

Segmentation Attributes

Attribute

Description

Type

id

The unique id of the segmentation. Is referenced by positions.

string

description

optional description of the segmentation to help the reader of the file. For reporting the id will be used as key into the translation tables.

string

segments

the list of segments in the segmentation

array of segment

Segment Attributes

Attribute

Description

Type

id

The unique id of the segment within the segmentation. Is referenced by positions.

string

segments

optional list of (sub)segments used to build a hierarchical segmentation

array of segment

description

optional description of the segment to help the reader of the file. For reporting the id will be used as key into the translation tables.

string

sortKey

optional sortKey to help sorting data from multiple files. If no sortKeys are provided, the order of segments in the file is relevant.

string

isNA

optional flag to state that this segment is actually not a discrete segment of the segmentation but rather something like

  • not available

  • not relevant

  • not assignable to single segment (e.g. multi-currency fund)

boolean

...

Example for segments on positions

The following examples show how the AssetClass segment is allocated to a position:

Case

Discussion

Example

1

Segment provided

Standard case: position will be reported under the specified segment.

Code Block
languagejs
"
breakdownSegments
segments":
[
{
{ 
"
segmentationId": "
AssetClass
", 
"
segmentId"
: "CASH"
}
,
{
"segmentationId":
 "GICS
", "segmentId
": "20104020"
}
]
2
NA-Segment provided
Position will be reported either under NA-segment or under "Others" segment depending on report configuration. The n.a. segment has to be listed in the segmentation definition (like any segment)
 Code Block
languagejs
"
breakdownSegments
segments": 
[
{
   	
{ "segmentationId
"
: "
AssetClass
", "segmentId
": "n.a."
 }
,

 

  
{
 
"segmentationId":
 "GICS
", "segmentId
": "20104020"
}

]
3
no segment provided
No segment known for position. Reporting will automatically create the "Others" segment to capture the position.
 Code Block
languagejs
"
breakdownSegments
segments": 
[
{
    
{ "segmentationId
"
: "
GICS
", "segmentId
": "20104020"
}

]

4
null Segment provided
not preferred, use case 3
 Code Block
languagejs
"
breakdownSegments
segments": 
[
{
   
 { "segmentationId": 
	"AssetClass
", 
"
segmentId"
: null
 }
,



   
{
 "
segmentationId": "
GICS
", 
"
segmentId"
: "20104020"
}

]
5
missing segmentId attribute
schema violation, use case 3
 Code Block
languagejs
"breakdownSegments": [
    { "segmentationId": "AssetClass" },
    { "segmentationId": "GICS", "segmentId": "20104020" }
]
6no breakdownSegments 
no segments provided
position always should have the 
 array 
property "
breakdownSegments
segments" - schema violation