Page Comparison

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 student domain makes a cross-reference to the "Country" domain country domain:

Image Removed

When a "student" master data record (MDR) is data records are POSTed, the request body would include a reference to a specific "country" master   data record:

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

When the "Student" MDR is referenced student data records are referenced (i.e. GET)  the response will insert the appropriate "Country" information 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 entire  data record (e.g. all of the properties for Mexico in  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   and "xrefLocation". The "xrefLocation" is  is the UUID or MDR path to another  reference master data record or even a property of the master another data record.  

{
	"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  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  entry in the modelSchema model schema for referencing a complete master data record would be:

   "xrefLocation": "/referencedomains/{domain-name}[:versionv<version>]"

e.g.

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

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

"homeCountry": "/mdrdrs/country:1v1/MEX"

Reference a Property in a

...

Data Record

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

e.g.

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

1. In a property called

...

1. homeCountry 
2. In a property

...

1. called immigrationAddress

...

GET the

...

address

...

 Property in the

...

countries

...

 Model Schema

GET /domains/country/versions/<country-version-uuid>/properties?version=1

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

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

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

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

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