Structure Reference Graph¶
Overview¶
Fusion Metadata Registry maintains the graph of references from one structure to another; for example, a Concept reference to a Codelist. References fall into different categories, depending on how the reference is defined:
- Absolute The reference includes an absolute value for all properties of the target structure (Agency ID, ID, Version, Sub IDs)
- Semantic The reference includes an absolute value for all properties with the exception of the Version, which uses semantic syntax, e.g. 1.0+.0
- Wildcard The reference may include wildcard properties, for example BIS:CL_FREQ(1.0).A% (any Code starting with the letter 'A')
In addition, there are two main categories of reference:
- Direct The reference is explicit in the model, e.g. a Concept directly references a Codelist by its URN
- Indirect The reference is derived, for example a Data Constraint constraining REF_AREA to UK indirectly references a Code 'UK' in a Codelist. The reference can only be determined by resolving the DSD that the Data Constraint references in order to determine the Codelist used for REF_AREA.
The FMR provides web services to provide the fully resolved graph of references, and a separate API to manage the references (dependencies) of structures.
API: Graph Resolution¶
List Direct, Indirect, and Resolved References for a Structure¶
API Details¶
Entry Point: /ws/registry/reference?urn=[urn]
Method: GET
Access: Public
Response¶
The response to this API is a fully resolved graph of references from the source structure to all target structures it references; this includes direct and indirect references. All semantic version references are resolved to absolute versions, and all wildcard references are resolved to the URNs they match. As this API dynamically calculates references based on the content of the FMR, the response to this call may vary as dependencies of the target structure are updated.
Response Syntax:
type Reference = {
source: string;
target: string;
indirect?: boolean;
};
type ReferenceList = Reference[];
Example:
GET https://registry.example.org/ws/registry/reference?urn=urn:sdmx:org.sdmx.infomodel.registry.DataConstraint=ESTAT:CR_BPM6_BOP_M(2.3)
[
{
"source": "urn:sdmx:org.sdmx.infomodel.registry.DataConstraint=ESTAT:CR_BPM6_BOP_M(2.3)",
"target": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=ESTAT:BPM6_BOP_M(2.3)"
},
{
"source": "urn:sdmx:org.sdmx.infomodel.registry.DataConstraint=ESTAT:CR_BPM6_BOP_M(2.3)",
"target": "urn:sdmx:org.sdmx.infomodel.datastructure.Dimension=IMF:BOP(2.1).ACCOUNTING_ENTRY",
"indirect": true
}
]
Note
The urn parameter must be an absolute URN and cannot reference semantic versions using wildcards. For instance urn:sdmx:org.sdmx.infomodel.registry.DataConstraint=ESTAT:CR_BPM6_BOP_M(2.0+.0) is not permitted.
Metadata time travel is also not supported. The current graph is always returned.
API: Dependency Management¶
List Direct References for a Structure¶
API Details¶
Entry Point: ws/secure/structure/dependency?urn=[urn]
Method: GET
Access: Restricted (Agency, Admin, Root)
Response¶
The response to this API is the direct references that the structure defines. The response does not include indirect references, and it does not resolve semantic references or wildcard references. The purpose of this API is to understand what references are defined by the structure, in order to support management of these references.
The response includes a source URN, which is the structure that has the reference, a target URN, which is the referenced structure, and a property, which is the property on the source structure and can be used to disambiguate between different references; for example, a RepresentationMap can reference two Codelists, one acting as a source for the mapping and the other as the target.
Response Syntax:
type Reference = {
source: string;
target: string;
property: string;
};
type ReferenceList = Reference[];
Example:
[
[
{
"source": "urn:sdmx:org.sdmx.infomodel.datastructure.DataAttribute=ESTAT:HICPAP(3.0).DECIMALS",
"target": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).DECIMALS",
"property": "concept"
},
{
"source": "urn:sdmx:org.sdmx.infomodel.datastructure.Dimension=ESTAT:HICPAP(3.0).IDX_TYPE",
"target": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).IDX_TYPE",
"property": "concept"
},
{
"source": "urn:sdmx:org.sdmx.infomodel.datastructure.TimeDimension=ESTAT:HICPAP(3.0).TIME_PERIOD",
"target": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).TIME_PERIOD",
"property": "concept"
}
]
Check Dependency Updates¶
API Details¶
Entry Point: ws/secure/structure/dependency/check
Method: POST
Access: Restricted (Agency, Admin, Root)
POST Content¶
The POST content defines a maintainable structure by its URN, and provides a dependencies map of current reference URN to new reference URN. The purpose of this API is to process the update, and run a reference check, reporting back which references could be updated and which would fail due to an unresolvable target structure.
Example:
{
"structure": "urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=ESTAT:HICPAP(3.0)",
"dependencies": {
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).COMMENT_DSET": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).COMMENT_DSET",
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).DATA_COMP": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).DATA_COMP",
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).IDX_TYPE": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).IDX_TYPE",
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).ITEM": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).ITEM",
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).IND_TYPE": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).IND_TYPE"
}
}
Response¶
The response to this check request is a map of valid changes and a map of invalid changes. The invalid changes are due to the reference being unresolvable (the target structure does not exist).
type UpdateResponse = {
structure: string;
valid: Record<string, string>;
invalid: Record<string, string>;
};
{
"structure": "urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=ESTAT:HICPAP(3.0)",
"valid": {
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).COMMENT_DSET": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).COMMENT_DSET",
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).DATA_COMP": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).DATA_COMP"
},
"invalid": {
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).IDX_TYPE": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).IDX_TYPE",
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).ITEM": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).ITEM",
"urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_PRICE(1.6).IND_TYPE": "urn:sdmx:org.sdmx.infomodel.conceptscheme.Concept=ESTAT:CS_NA(1.16).IND_TYPE"
}
}
Save Dependency Updates¶
API Details¶
Entry Point: ws/secure/structure/dependency/update
Method: POST
Access: Restricted (Agency, Admin, Root)
POST Content¶
The POST content is the same as the Check Dependency Update API. The difference in behaviour is that this API will perform the updates, and persist them to the FMR database.
Response¶
The response is an HTTP status 200 if successful. If there is an error in the update, an error response will be reported.