Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

 

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" master data record (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 UUID or MDR path to another  reference master data record or even a property of the master 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 "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 modelSchema for referencing a complete master data record 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 master record e.g.:

"homeCountry": "/mdr/country:1/MEX"

Reference a Property in a Master Data Record

When POSTing the reference, the "xrefLocation" entry in the modelSchema for referencing a property of a master data record would be:

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

UUIDs Instead of Domain/MDR Paths

While not as human-friendly, UUIDs can be used to be more lookup-friendly to the web service. Since YOUnite uses UUIDs for lookups in the underlying store, UUIDs can be considered if there are performance concerns (for example, for domains that are frequently referenced) but it has not been quantified how much performance is actually gained by using them.

UUID for a domain/s properties is returned with the following:


GET /domains/<domain-name>/properties


{
	"properties": [{
			.
		"uuid": "bab4b589-be75-4e7c-93c8-c89e037d307d",
			.
			.
		"propertyName": "capital",
			.
			.
		}, {
			.
		"uuid": "7388d88b-d2b8-4585-a08f-ab373c1b0043",
			.
			.
		"propertyName": "capital.city",
			.
			.
		}, {
  			.
			.
			.
	}]
}


To get the UUIDs for a MDR's properties use:

    GET /mdr/<domain-name>/<display-value>?refs=true

For example, to post a "student" MDR with a reference to a "country" MDR using an UUID:

    GET /mdr/country/CAN?refs=true


{
	"name": {
		"value": "Canada",
		"_self": "9a472159-fc7c-4730-b8af-5007b26f890c"
	},
	"immigrationAddress": {
		"Street": {
			"value": "220 4th Avenue, SE, Room 210",
			"_self": "df879f43-cd93-4f5e-b77a-4ac64e0b5ba4"
		},
		"city": {... },
		"province-state": {},
		"postal-code": {}
	},
		.
		.
		.
}


Then, POST the student entity with the appropriate UUID for the cross-references

    POST /mdr/students


{
	"firstname": "Jane",
	"lastname": "D'oe",
		.
		.
	"homeCountry": "9a472159-fc7c-4730-b8af-5007b26f890c",
	"immigrationAddress": "08c257b-74ac-406e-b56f-9cbbab87a57f"
}
  • No labels