A data domain (domain) can cross-reference another in its definition creating a relationship between two or more domains. In the following diagramexample, the "Student" domain student
domain makes a cross-reference to the "Country" domain country
domain:
Table of Contents |
---|
When a "student
" master data record (MDR) is data records are POSTed, the request body would include a reference to a specific "country
" master data record:
Code Block |
---|
{ "studentID": "XYZ-123", "name": "Juana Masa", "homeCountry": "/mdrdrs/country:1v1/MEX", "birthday": "946684800" } |
When the "Student" MDR is referenced student
data records are referenced (i.e. GET) the response will insert the appropriate "Country" information country
information:
Code Block |
---|
{ "studentID": "XYZ-123", "name": "Juana Masa", "homeCountry": { "name": "Mexico", "abbreviation": "MEX", "capitalCity": "Mexico City" }, "birthday": "946684800" } |
...
The cross-reference can be to an entire master entire data record (e.g. all of the properties for Mexico
in in the MDRdata record):
"homeCountry": "/mdrdrs/country:1v1/MEX",
Or for a specific property in the master the data record (e.g. just the country name):
"homeCountry": "/mdrdrs/country:1v1/MEX/name",
Defining a Cross-Reference in the modelSchema
To reference another domain, include the cross-reference property definitions "type": "uri"
, "uriType": "xref"
and and "xrefLocation"
. The "xrefLocation
" is is the UUID or MDR path to another reference master data record or even a property of the master another data record.
Code Block | ||
---|---|---|
| ||
{ "name": <reference-name>, "modelSchema": { "properties": { "<property1>": { "type": "uri", "uriType": "xref", "xrefLocation": "<path (or UUID) of a domain or domain property>", "" ...other item1 properties.... }, "<property2>": { ... } } } } |
xrefLocation
When defining a reference, the "the domain
" path path to the reference is used. When When POSTing data for the reference the "/mdr" data record path is used.
Some examples will help clarify:
Reference to an Entire
...
Data Record
When POSTing the reference, the "xrefLocation
" entry entry in the modelSchema model schema for referencing a complete master data record would be:
"xrefLocation": "/referencedomains/{domain-name}[:versionv<version>]"
e.g.
Code Block |
---|
"homeCountry": { "type": "uri", "uriType": "xref", "xrefLocation": "/domaindomains/country:1v1" } |
When POSTing the data for the reference use the "displayName
" of of the desired master data record e.g.:
Code Block |
---|
"homeCountry": "/mdrdrs/country:1v1/MEX" |
Reference a Property in a
...
Data Record
When POSTing the reference, the "xrefLocation
" entry entry in the modelSchema model schema for referencing a property of a master data record would be:
"xrefLocation": "/referencedomains/{domain-name}[:version][/property]"
e.g.
Code Block |
---|
"homeCountry": { "type": "uri", "uriType": "xref", "xrefLocation": "/domaindomains/country:1v1/name" } |
...
A Cross Reference Example
The following demonstrates in more detail the example where properties from an existing "country
" domain is domain are to be referenced by a new domain called "students
". Assume Assume the "country
" domain domain contains many properties including the country " name " and the address for the immigration office. The "students" domain student
domain will reference the "countries
" domain twice 1) domain twice:
- In a property called
...
-
homeCountry
- In a property
...
- called
immigrationAddress
...
GET the
...
address
...
Property in the
...
countries
...
Model Schema
GET /domains/countryversions/<country-version-uuid>/properties?version=1
Code Block | ||
---|---|---|
| ||
[ { . . "propertyName": "immigrationAddress", "propertyType": "node", . . }, { . . "propertyName": "name", "propertyType": "string" . . } ] |
Create a New students
Domain and Add the Cross-Reference
...
To the First Version's Model Schema
POST /domains/versions/<students-domain-uuid>
Code Block |
---|
{ "name": "students", "modelSchema": { "properties": { "homeCountry": { "type": "uri", "uriType": "xref", "xrefLocation": "/mdrdomains/country:v1/name" }, "immigrationAddress": { "type": "uri", "uriType": "xref", "xrefLocation": "/mdrdomains/country:v1/immigrationAddress" }, . . . } } } |
Note that `homeCountry` is homeCountry
is a primitive type while `immigrationAddress` is immigrationAddress
is a node and contains contains several items such as street, city, province-state, and postal-code.
Again, the "stuents" domain students
domain could just reference the "country
" MDR data record once, which would cause the entire "country
" MDR data record to be inserted.
How to Establish Circular Cross-References
Consider the situation where a "state
" domain domain needs to reference to "country" and "country" needs reference country
and country
needs a reference back to multiple "state
" MDRs data records.
This creates a "chicken-or-the-egg" problem since the schema for one will exist before the other. To remedy this problem, one of the domains can be updated after both are created.
For example:
1. POST the domain modelSchema for "state" with a modelSchema that includes a reference to "country" with no `xrefLocation`the state
domain
:
Code Block | ||
---|---|---|
| ||
"name": { "type": "string" }, "country": { "type": "uri", "uriType": "xref" } |
2. POST the domain for "country
" with with a modelSchema model schema that includes a reference to "state
" including including the `xrefLocation` xrefLocation
:
Code Block | ||
---|---|---|
| ||
"name": { "type": "string" }, "state": { "type": "uri", "uriType":"xref", "xrefLocation": "/domain/state:v1/name" } |
3. PUT PATCH the domain for "state
" with with a modelSchema model schema that includes the reference to "country
":
Code Block | ||
---|---|---|
| ||
"name": { "type": "string" }, "country": { "type": "uri", "uriType": "xref", "xrefLocation": "/domain/country:v1/name" } |
Data can be posted only if all uri's of type `xref` have valid `xrefLocation`s xref
have a valid xrefLocation
.
NOTE: PUTing PATCHing a domain:version is denied if any data is POSTed to the domain:versionit.