Unique Identifiers¶

There is a single top-level uids element on all Objects. This element is a map from scope to id with a maximum of 8 total elements. Citrine reserves one scope and will not allow a value to be set: "ID". This reserved element is referred to as the Citrine ID, and will always point to a version 4 random UUID generated by the Citrine Platform. The remaining elements of the map are referred to as "alternative identifiers" or "customer identifiers". The id component of customer identifiers need not be globally unique on its own, but the pair of (scope, id) must be unique. Equivalently, every alternative uid must be unique within its designated scope.

Each scope, id pair can be associated with exactly one object. Scopes should be interpreted as case-insensitive, e.g., MyId and MYID refer to the same scope.

---

Citrine ID¶

The unique identifier for all Objects on the platform

Scope	Value type	Description
ID	String	string representation of a random Version 4 UUID

Constraints¶

Field name	Relationship	Constraint
len(id)	==	36
id	parses to	Version 4 Random UUID

Example¶

{
    "uids" : {
        "id" : "f36099b9-2ca1-4ff7-afd2-dd226dc79e66"
    }
}

---

Alternative IDs¶

A scope and identifier that, together, form an alternative unique identifier for an object platform-wide.

Field name	Value type	Description
uids	Map[String, String]	a map from scope to id

Constraints¶

Field name	Relationship	Constraint
len(uids)	<=	8
len(scope)	<=	128, UTF-8 encoded
len(id)	<=	512, UTF-8 encoded
scope		cannot include ::

Example¶

{
    "uids": {
        "NIST-SRM" : "141e"
    }
}

Invalid Example¶

This scope field is not allowed by the Citrine Platform:

{
    "uids": {
        "NIST::SRM" : "141e"
    }
}

---

LinkByUID¶

Any nested object with a unique identifier can be replaced by a LinkByUID object.

In general, the SDK for the data model implementation should handle translating nested structures into LinkByUID objects at write time--users of the SDK should only need to specify a LinkByUID object under very specific circumstances.

Field name	Value type	Description
type	String	"link_by_uid"
scope	String	The scope of the unique identifier, e.g., "ID" for the Citrine ID
id	String	The value of the identifier within that scope, e.g., a UUID4 for the Citrine ID

Example¶

{
    "type" : "link_by_uid",
    "scope" : "id",
    "id"    : "8ee36a2e-66ce-4106-81c9-2b73cc0c6cb9"
}

{
    "type" : "link_by_uid",
    "scope" : "NIST-SRM",
    "id"    : "141e"
}