Domain Cross References

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

    "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 "students" domain will reference the "countries" domain twice 1) In a property called "homeCountry" and 2) a property called "immigrationAddress".

GET the "address" Property in the"countries" modelSchema

GET /domains/country/properties?version=1

[
	{
			.
			.
		"propertyName": "immigrationAddress",
		"propertyType": "node",
				.
			.
	},
	{
			.
			.
		"propertyName": "name",
		"propertyType": "string"
			.
			.
	}
]

Add the Cross-Reference into the "students" modelSchema 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 "stuents" 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 modelSchema 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 modelSchema 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 modelSchema 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.