Page Comparison

...

Once a version of a domain is created and its master data records (MDRs) are loaded (or mapped in a federated model), it can be referenced by other data domains, adaptors and by API consumers as a source of truth. Domains have version numbers so that other domains, adaptors and applications can bind to a specific domain and version (e.g. students:v3).

Domain Types

The master data for a domain can be stored either:

...

FEDERATED domains do not store their data centrally in YOUnite but retrieve and update the data on the systems in which it resides. For example, MIS, ERP or CRM systems. Federated domains require adaptors and metadata and scope configurations and are covered in detail *TODO: TUTORIAL ON FEDERATED*

Domain Model Schemas

A domain model schema (model) is a JSON object describing the schema for a data domain; it defines the properties that make up the domain's schema. The root node of the model schema is the properties element. See Data Domains : and Multi-Domain MDM and Data Domains : and Multi-Domain MDM for ModelSchema Properties below.

POST the Domain

The first step in creating a domain is to define the domain name, its type and the owning zone:

...

The model is not created in this step. Models are tied to specific versions covered below.

POST a Domain Version

With the domain in place, its first version can be created. The domain version defines the properties that make up domain version's model. The domain version numbers are automatically generated and start with 1 and continue in ascending order. The root node of the model schema is the properties element. See Data Domains : and Multi-Domain MDM and Data Domains : and Multi-Domain MDM below.

A domain version is defined with a domain JSON Object as described below:

...

Code Block

language	text

{
	"modelSchema": {
		"properties": {
			"<property-name>": {
				"type": "<property-type>",
				...item1 properties....
			},
			"<property-name>": {
				 ... 
			}
		}
	},
	"displayProperty": "<property-name>",
	"uniquenssRuless": "<property-name1> [, <property-name2>, .....]"
}

Descriptions of the Domain Version Properties

property	required	valid values	description
`modelSchema`	yes	See Data Domains : and Multi-Domain MDM and Data Domains : and Multi-Domain MDM below.	A JSON model describing the schema for the data domain; it defines the properties that make up the domains schema. The root node of the model schema is the `properties` element. See Data Domains : and Multi-Domain MDM and Valid Types for ModelSchema Properties below.
`displayProperty`	yes	A valid model schema property name	A property defined in the `modelSchema` that acts as an index for the domain. The data values for the `displayProperty` must always be unique. See Retrieving Master Data; the Display Property below.
`uniquenessRules`	no	One or more valid model schema property names	Required data and their associated rules that are cache'd to make sure duplicate data entries are not POSTed to the domain. This defaults to the `displayProperty` if it is not provided. See Data Domains : and Multi-Domain MDM below.

The Default Domain Version

The first version of a domain is the default version and will remain the default version if more versions of a given domain are created.The PATCH method for the /domains/<domain-uuid> endpoint can be used to change a domain's default version. See the YOUnite API for implementation details.

Creating a Domain is Three-Step Process

For example, we'll create a centralized data domain and load one MDR:

POST the Domain
POST a Domain Version
POST (or Map) the Master Data

POST the Domain
For example, to create a simple states domain :
POST /domains
Code Block
language js
{ "name": "states", "zoneUuid": "a1aca070-846f-44e5-9471-c73b46c35f4a", "domainType": "MASTER_CENTRALIZED" }
The location header returned provides the URI for POSTing a domain version below.
e.g.
Location /domains/7f28180b-7d9f-42b5-b5ed-d4a0e7ec09fc
POST a Domain Version
POST /domains/versions/7f28180b-7d9f-42b5-b5ed-d4a0e7ec09fc
POST Master Data Records to the Domain
Once the domain/version has been created, master data can be POSTed to it using the /mdr endpoint:
POST /mdrs
Code Block
language js
{ "name": "states", "version": 1, "json": { "name" : "California", "abbreviation" : "CA" } }

Retrieving Master Data

The MDRs for a the default version of a domain can be retrieved with the following:

...

POST /mdrs?filters=name:<domain-name>,version:<version>

The Display Property

Each domain must have a display property (displayProperty). The display property acts as a primary key for the domain. For example, the states domain above uses the abbreviation property as the display property, Use the /mdrs endpoint and the appropriate domain and display property to GET an MDR:

...

GET /mdrs?filters=name:states,version:1,displayProperty:CA

Display Property Rules

The value provided for the displayProperty must be unique between all domain entries of a given domain type (e.g. each entry in the state domain must have a unique stateName).
Only one property in a domain can be the displayProperty. If more than one property is required to ensure uniqueness see the Data Domains : and Multi-Domain MDM below.
Display properties are limited to type STRING.
Properties designated as the displayProperty are required; i.e. null values are not allowed.
Display properties are case sensitive e.g. "California" is NOT equal to "california".

Uniqueness Rules Property

Uniqueness Rules

MDM provides uniqueness rules for MDR duplicate prevention in the case where a simple displayProperty won't suffice.
Optionally, specify a comma-separated list of domain properties whose values, in aggregate, must be unique across all the MDRs for the domain.
If not provided, MDM will use the displayProperty as the uniquenessRules.
Uniqueness rule properties are limited to type STRING
Values in uniquenessRules properties are compared case sensitively e.g. "California" is NOT equal to "california".

Code Block

language	text

{
	"name": <domain-name>,
	"domainType": "CENTRALIZED",
	"modelSchema": {
		"properties": {
			"<property-name>": {
				"type": "<property-type>",
				...item1 properties....
			},
			"<property-name>": {
				 ... 
			}
		}
	},
	...
	"uniquenessRules": "<property-name>,<property-name>,..."
}

Model Schema Properties

Valid Property Names

Must start with a letter or "\_" (underscore).
Can contain digits, "-" (dash) and "\_" (underscore) only.
Can be up to 64 characters in length.
Are case in-sensitive.
If two properties have the same name at the same level only one will be used. In the Example 1, only one name property will be used. In Example 2 both will be used ( name occurs at different levels in the JSON structure):

...

Code Block

title	Example 2

{
	"properties": {
		...
		"owner": {
			"name": {...},
			"phone": {...},
			....
		},
		"pet": {
			"name": {...},
			"classification": {...},
			....
		},
		....
	}
}

Valid Types

Each property with the exception of a node, requires a type property e.g.:

Code Block
"type": "string"

Node

A container-node item is a node that contains sub-properties. For example, address is a container node with the sub-items city and state.

...

Property	Description
`required`	A non-null value for this item must be provided (`false` by default). Items inside the container-node can override the parent container node's required setting.

string

A string of character variables. The following properties are applied when data is posted for this item:

Property	Description
`min`	Minimum string length.
`max`	Maximum string length.
`regex`	String must match the regex pattern.
`default`	If the item is not provided or is null, the default value is used.
`required`	A non-null value for this item must be provided (`false` by default).

int

A numeric, whole number.

Property	Description
`min`	Minimum value allowed.
`max`	Maximum value allowed.
`regex`	String must match the regex pattern.
`default`	If the item is not provided or is null, the default value is used.
`required`	A non-null value for this item must be provided (`false` by default).

number

A numeric, decimal number with up to 15 bits of precision.

Property	Description
`min`	Minimum value allowed.
`max`	Maximum value allowed.
`regex`	String must match the regex pattern.
`default`	If the item is not provided or is null, the default value is used.
`required`	A non-null value for this item must be provided (`false` by default).

boolean

A boolean, allowing only the two values of true or false

Property	Description
`default`	If the item is not provided or is null, the default value is used.
`required`	A non-null value for this item must be provided (`false` by default).

enum

Enumerations (enums) can be either a primitive type (string, int, or a number) or, a cross-reference to an entire set or subset of MDRs in another domain.

Property	Description
`enumType`	Types of enums: int: A numeric whole number. number: A numeric, decimal number with up to 15 bits of precision. string: A string of character variables. uri: A cross-reference to another domain; use in conjunction with `xrefLocation.`
`xrefLocation`	If `enumType` is set to `uri` then `xrefLocation` points to the domain that makes up the elements of the enumeration. For example, if a version of a domain countries contains a list of MDR values that represent all countries then a domain can reference it by specifying an enumeration type of `uri` and the desired domain and version number: `enumType: uri` `xrefLocation`: `/domains/countries:v1` A subset of the MDR values in the domain can be specified using the `data` property.
`data`	An array containing a comma separated list of enum values e.g. `"data":["Mays", "McCovey", "Marichal"]` Is a three-item string enumeration. If the `enumType` is uri the list of values in the `xrefLocation` can be limited to the subset of MDRs whose display values contained in the `data` array. For example, if `/domains/countries:v1` contains a list of all countries but the domain should only reference countries in North America, then the `data` entries would be: `"data":["CANADA", "USA", "MEXICO"]` Assuming the display values for Canada, the United States and Mexico are those shown above in the data elements.
`default`	If the item is not provided or is null, the `default` value is used.
`required`	A non-null value for this item must be provided (`false` by default).

uri

A properly formed Uniform Resource Locator (URI). By default, a property of type uri can be any valid URI or it can be limited by a regex pattern or to a domain cross-reference (xrefLocation: "xref").

...

Property	Description
`uriType`	The uri type (e.g. url, blob, xref).
`xrefLocation`	The location of the domain item or domain item data element. Used in conjunction with `"uritype": "xref"`.
`regex`	String must match the regex pattern.
`default`	If the item is not provided or is null, the default value is used.
`required`	A non null value for this item must be provided (false by default).

array

An array can contain any type of value including nodes and nested arrays.

Property	Description
`minItems`	Minimum items allowed in the array.
`maxItems`	Maximum items allowed in the array
`regex`	String must match the regex pattern.
`default`	If the item is not provided or is null, the default value is used.
`required`	A non-null value for this item must be provided (`false` by default).

Rules About Required and Default Values

If a domain property has a default value defined in its modelSchema, then any domain MDR posted will use the default value if the property is either not include or is sent in with a null value.

...

If both required and default are used to define a given property, then default is ignored and POSTing data must include the required property.

POST a Domain Version

Following is a simple example of model for a domain version.

...

Versions Compared

Old Version 59

New Version 60

Key

Domain Types

Domain Model Schemas

POST the Domain

POST a Domain Version

Descriptions of the Domain Version Properties

The Default Domain Version

Creating a Domain is Three-Step Process

POST the Domain

POST a Domain Version

POST Master Data Records to the Domain

Retrieving Master Data

The Display Property

Display Property Rules

Uniqueness Rules Property

Uniqueness Rules

Model Schema Properties

Valid Property Names

Valid Types

Node

string

int

number

boolean

enum

uri

array

Rules About Required and Default Values

POST a Domain Version