Interface "Segmentations"
Status | IMPLEMENTED | ||
|---|---|---|---|
Usage & contents |
| ||
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.
| ||
Schema | |||
Error handling | If the request can't be fulfilled an appropriate response status code (4xx or 5xx) must be used. Possible errors could be
The body of the response should contain information about the reason of the error in plain text or as json object. | ||
Consistency rules | The following rules should be adhered to by any response and will eventually be checked when consuming a response: Consistency Rules* 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 |
| ||
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
| boolean |
Breakdown 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. | "breakdownSegments": [
{ "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) | "breakdownSegments": [
{ "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. | "breakdownSegments": [
{ "segmentationId": "GICS", "segmentId": "20104020" }
]
|
| 4 | null Segment provided | not preferred, use case 3 | "breakdownSegments": [
{ "segmentationId": "AssetClass", "segmentId": null },
{ "segmentationId": "GICS", "segmentId": "20104020" }
]
|
| 5 | missing segmentId attribute | schema violation, use case 3 | "breakdownSegments": [
{ "segmentationId": "AssetClass" },
{ "segmentationId": "GICS", "segmentId": "20104020" }
]
|
| 6 | no breakdownSegments provided | position always should have the array "breakdownSegments" - schema violation |
Add Comment