A data domain (domain) can cross-reference another in its definition creating a relationship between two or more domains. In the following example, the student
domain makes a cross-reference to the country
domain:
Table of Contents |
---|
When a student
data records are POSTed, the request body would include a reference to a specific country
data record:
...
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.
...
When defining a reference, the the domain
path to the reference is used. When When POSTing data for the reference the data record path is used.
Some examples:
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": { "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.
...