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
data records is are POSTed, the request body would include a reference to a specific country
data record:
Code Block |
---|
{ "studentID": "XYZ-123", "name": "Juana Masa", "homeCountry": "/mdrsdrs/country:v1/MEX", "birthday": "946684800" } |
When the student
data record is referenced records are referenced (i.e. GET) the response will insert the appropriate country
information:
...
The cross-reference can be to an entire data record (e.g. all of the properties for Mexico
in the data record):
"homeCountry": "/mdrsdrs/country:v1/MEX",
Or for a specific property in the data record (e.g. just the country name):
"homeCountry": "/mdrsdrs/country:v1/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 the path to another another data record or a property of the another data record.
Code Block | ||
---|---|---|
| ||
{ "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 data record would be:
...
Code Block |
---|
"homeCountry": "/mdrsdrs/country:v1/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 data record would be:
"xrefLocation": "/domains/{domain-name}[:version][/property]"
e.g.
Code Block |
---|
"homeCountry": { "type": "uri", "uriType": "xref", "xrefLocation": "/domains/country:v1/name" } |
...
A Cross Reference Example
The following demonstrates in more detail the example where properties from an existing country
domain is are to be referenced by a new domain called students
. Assume 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 In a property called
immigrationAddress
GET the address
Property in the countries
Model Schema
GET /domains/versions/<country-version-uuid>/properties
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>
...
Note that homeCountry
is a primitive type while immigrationAddress
is a node and contains contains several items such as street, city, province-state, and postal-code.
Again, the students
domain could just reference the country
data record once, which would cause the entire country
data record to be inserted.
...
Consider the situation where a state
domain needs to reference to reference country
and country
needs a reference back to multiple state
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 modelSchema for the state
domain
:
...
Data can be posted only if all uri's of type xref
have a valid xrefLocation
`s.
PATCHing a domain:version is denied if any data is POSTed to it.
...