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 makes a cross-reference to the country
domain:
Table of Contents |
---|
When a student
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 data records are referenced (i.e. GET) the response will insert the appropriate country
information:
...
The cross-reference can be to an entire master entire data record (e.g. all of the properties for Mexico
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 "xrefLocation"
. The xrefLocation
is the MDR path to another MDR data record or a property of the another MDRdata 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 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 in the model schema for referencing a complete MDR 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 the desired MDR 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 in the model schema for referencing a property of a MDR 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/country/versions/<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: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 moreit.