A data domain (domain) can cross-reference another in its definition creating a relationship between two or more domains. In the following diagram, the student
domain makes a cross-reference to the country
domain:
When a student
MDR is POSTed, the request body would include a reference to a specific country
master data record:
{ "studentID": "XYZ-123", "name": "Juana Masa", "homeCountry": "/mdr/country:1/MEX", "birthday": "946684800" }
When the student
MDR is referenced (i.e. GET) the response will insert the appropriate country
information:
{ "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 data record (e.g. all of the properties for Mexico
in the MDR):
"homeCountry": "/mdr/country:1/MEX",
Or for a specific property in the master data record (e.g. just the country name):
"homeCountry": "/mdr/country:1/MEX/name",
Defining a Cross-Reference in the modelSchema
To reference another domain, include the cross-reference property definitions "type": "uri"
, "uriType": "xref"
and "xrefLocation"
. The xrefLocation
is the MDR path to another MDR or a property of the another MDR.
{ "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 domain
path to the reference is used. When POSTing data for the reference the MDR path is used. Some examples will help clarify:
Reference an Entire Master Data Record
When POSTing the reference, the xrefLocation
entry in the model schema for referencing a complete MDR would be:
"xrefLocation": "/reference/{domain-name}[:version]"
e.g.
"homeCountry": { "type": "uri", "uriType": "xref", "xrefLocation": "/domain/country:1" }
When POSTing the data for the reference use the displayName
of the desired MDR e.g.:
"homeCountry": "/mdr/country:1/MEX"
Reference a Property in a Master Data Record
When POSTing the reference, the xrefLocation
entry in the model schema for referencing a property of a MDR would be:
"xrefLocation": "/reference/{domain-name}[:version][/property]"
e.g.
"homeCountry": { "type": "uri", "uriType": "xref", "xrefLocation": "/domain/country:1/name" }
An Example
The following demonstrates in more detail the example where properties from an existing country
domain is to be referenced by a new domain called students
. Assume the country
domain contains many properties including the country name and the address for the immigration office. The student
domain will reference the countries
domain twice:
- In a property called
homeCountry
- A property called
immigrationAddress
GET the address
Property in the countries
Model Schema
GET /domains/country/properties?version=1
[ { . . "propertyName": "immigrationAddress", "propertyType": "node", . . }, { . . "propertyName": "name", "propertyType": "string" . . } ]
Add the Cross-Reference into the students
Model Schema and POST a New Domain
POST /domains
{ "name": "students", "modelSchema": { "properties": { "homeCountry": { "type": "uri", "uriType": "xref", "xrefLocation": "/mdr/country:v1/name" }, "immigrationAddress": { "type": "uri", "uriType": "xref", "xrefLocation": "/mdr/country:v1/immigrationAddress" }, . . . } } }
Note that homeCountry
is a primitive type while immigrationAddress
is a node and contains several items such as street, city, province-state, postal-code.
Again, the students
domain could just reference the country
MDR once which would cause the entire country
MDR to be inserted.
How to Establish Circular Cross-References
Consider the situation where a state
domain needs to reference to country
and country
needs a reference back to multiple state
MDRs.
This creates a problem since the schema for one will exist before the other. To remedy one of the domains can be updated after both are created. For example:
1. POST the domain for state
with a model schema that includes a reference to country
with no xrefLocation
:
"name": { "type": "string" }, "country": { "type": "uri", "uriType": "xref" }
2. POST the domain for country
with a model schema that includes a reference to state
including the xrefLocation
:
"name": { "type": "string" }, "state": { "type": "uri", "uriType":"xref" }
3. PUT the domain for state
with a model schema that includes the reference to country
:
"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.
NOTE: PUTing a domain is denied if any data is POSTed to the domain:version
.
Using UUIDs
The underlying store in YOUnite uses UUIDs to access data elements. UUIDs can be used instead of domain paths. See Using UUIDs Instead of Domain or MDR Pathnames for more.