Cross Domains

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:

When a student data records are POSTed, the request body would include a reference to a specific country  data record:

{
	"studentID": "XYZ-123",
	"name": "Juana Masa",
	"homeCountry": "/drs/country:v1/MEX",
	"birthday": "946684800"
}

When the student data records are 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  data record (e.g. all of the properties for Mexico in the data record):

    "homeCountry": "/drs/country:v1/MEX",

Or for a specific property in the  data record (e.g. just the country name):

    "homeCountry": "/drs/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 path to another data record or a property of the another data record.  

{
	"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 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:

   "xrefLocation": "/domains/{domain-name}[:v<version>]"

e.g.

"homeCountry": {
	"type": "uri",
	"uriType": "xref",
	"xrefLocation": "/domains/country:v1"
}

When POSTing the data for the reference use the displayName of the desired data record e.g.:

"homeCountry": "/drs/country:v1/MEX"

Reference a Property in a Data Record

    "xrefLocation": "/domains/{domain-name}[:version][/property]"

e.g.

"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 are 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:

1. In a property called homeCountry 
2. In a property called immigrationAddress

GET the address Property in the countries Model Schema

GET /domains/versions/<country-version-uuid>/properties

[
	{
			.
			.
		"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>

{
	"modelSchema": {
		"properties": {
			"homeCountry": {
				"type": "uri",
				"uriType": "xref",
				"xrefLocation": "/domains/country:v1/name"
			},
			"immigrationAddress": {
				"type": "uri",
				"uriType": "xref",
				"xrefLocation": "/domains/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, 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.

How to Establish Circular Cross-References

Consider the situation where a state domain needs 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:

"name": {
	"type": "string"
}

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",
	"xrefLocation": "/domain/state:v1/name" 
}

3. PATCH 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 a valid xrefLocation.

PATCHing a domain:version is denied if any data is POSTed to it.