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