Short Identifier

Owned by Adaptavist ScriptRunner for Confluence Cloud
Oct 28, 2020
2 min read

A short identifier is an identifier for a specific instance of a resource type.

Both short identifiers and CSIDs uniquely identify a resource (or "record") in CollectionSpace. You can use a short identifier as an alternative to a CSID in some - but not yet all - of the places that you can use a CSID.

Short identifiers tend to be more human-readable than CSIDs. Examples:

A short identifier for a Person Authority resource:

OurMuseumPersonAuthority

A CSID for the same resource:

2257d961-4a37-490a-8074

Short Identifiers in URIs

When sending requests to the CollectionSpace Services Layer via its REST APIs, you can in some cases use a short identifier, in place of a CSID, in your request URI, as a means of identifying a specific resource (record).

Within URIs, short identifiers are placed inside a set of parens, following the URN expression urn:cspace:name, like this:

urn:cspace:name({short-identifier})

For instance, a particular Person Authority might alternately be identified via either of the following types of URIs, which use a short identifier value and a CSID, respectively:

Using a short identifier

General format, where {short-identifier} below represents a short identifier value:

/cspace-services/personauthorities/urn:cspace:name({short-identifier})

Example:

/cspace-services/personauthorities/urn:cspace:name(OurMuseumPersonAuthority)

Using a CSID

General format, where {csid} below represents a CSID value:

/cspace-services/personauthorities/{csid}

Example:

/cspace-services/personauthorities/2257d961-4a37-490a-8074

Places Short Identifiers are Used

Short identifiers are currently used to uniquely identify:

  • Authorities (aka "vocabularies within an authority"), such as Person Authorities or Organization Authorities.
  • Terms ("items") within an authority.
  • Vocabularies ("controlled lists")
  • Terms ("items") within a vocabulary.

Every one of these resources may be identified by either a short identifier, or by its CSID.

In the future, short identifiers may potentially be used in additional contexts, such as to uniquely identify object (cataloging) or procedural resources. Currently, however, only CSIDs may be used as identifiers for such resources.

In addition to being used within request URIs, short identifiers are also used in refNames.

Format of Short Identifiers

Short identifiers consist only of characters in the ranges of A-z, a-z, and digits in the range of 0-9, without whitespace or any other characters. A short identifier cannot be empty (or null), nor can it consist only of whitespace.

Automatically-created Short Identifiers

Some short identifiers are automatically created when a resource is created. These identifiers may in some cases be based on the contents of one or more fields in the resource, such as a display name field. They may also include a timestamp, hash value, or some other additional content - not necessarily intended to be human-readable - to help avoid uniqueness collisions.

Example:

OurMuseumPersonAuthority1333737737040

Permanence of Short Identifiers

Once created and assigned to a resource, short identifiers never change, even if the contents of the resource are changed, such as a change in the value of a display name field.

Uniqueness of Short Identifiers

Short identifiers are intended to be unique within their context. For example, short identifiers for terms in a vocabulary ("controlled list") are intended to be unique within that vocabulary.

See Also