A refName is an identifier used within a CollectionSpace system that bundles a value together with metadata about the value's context.

Examples

The following are two representative examples of CollectionSpace refNames:

This refName identifies an "Entry Methods" vocabulary - an enumeration of terms that describe the methods by which objects may enter a museum:

This refName identifies a specific vocabulary term (or item), "Loan", as well as the parent vocabulary to which the term belongs, "Entry Methods":

Both of the refName examples above use IDs as identifiers. Some refNames may instead use names - which point to the same resources as their corresponding IDs - as identifiers, or mix and match a combination of IDs and names as identifiers in any position. The following examples depict several alternate ways of expressing the same resources as those above: an "Entry Methods" vocabulary, and a "Loan" term or item in that vocabulary:

Purpose for using refNames

refNames make it possible to:

• Convey and store structured data wherever simple text values might otherwise be used.
• Provide services-agnostic data, that does not depend on the specifics of internal implementations.
• Make values and their contextual metadata portable for import and export.

Uses of refNames

CollectionSpace refNames are currently used in the following contexts:

• Vocabularies and vocabulary items
• Persons, Organizations, and other resources which may be accessed via a vocabulary-like interface.

Format of refNames

CollectionSpace refNames are structured Strings that contain values, along with metadata describing the context of those values.

Every CollectionSpace refName is an instance of a Uniform Resource Name (URN), an Internet-standard for "persistent, location-independent resource identifiers."

Consistent with the URN specification, a CollectionSpace refName consists of the following components:

• A "urn:" prefix, which denotes that the refName is an instance of a URN.
• A URN namespace identifier (NID). In CollectionSpace refNames, this namespace is always "cspace".
• A colon (":") character as a delimiter.
• A URN namespace-specific string (NSS), which carries the data unique to a particular refName.

A refName's namespace-specific string (NSS), in turn, consists of:

• A NSS-specific namespace, either owned by CollectionSpace or by another institution, such as a provider of structured data (e.g. the Getty Vocabulary Program), or a specific museum or other heritage institution. This namespace is an Internet domain name, with its elements in order from most to least significant (e.g. "org.collectionspace.demo").
• A colon (":") character as a delimiter.
• One or more resource part(s).

Each resource part in the NSS, in turn, consists of:

• A resource type within the NSS-specific namespace. Examples of resource types within CollectionSpace-owned namespaces include "vocabulary", "personauthority" and "person".
• A colon (":") character as a delimiter.
• A resource identifier type, whose value will be either "id" or "name".
• An identifier of a specific instance of that resource type. This identifier is enclosed in parentheses. The identifier:
  • May be an ID, such as a CollectionSpace ID (CSID), or a String called a "short identifier" (consisting of 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).
  • Must be consistent with the resource identifier type: an ID value follows a resource identifier type of "id", while a short identifier value follows a resource identifier type of "name".
  • Cannot be empty (or null), or consist only of whitespace.
• An (optional) displayed value of the resource, sometimes referred to as a "display name." Simply put, this is the value of that resource, either currently or at a point in time. This value is enclosed within single quotes. The value of a resource may at times be empty (null). Two guidelines regarding the optional nature of this displayed value:
  • Parent resource parts - parts that are pointed to by a child resource part within the same refName - may omit their displayed value and its enclosing single quotes.
  • However, although optional, the resource part which ends a refName should always contain a displayed value, as this obviates the need to perform a lookup of that value through its identifier, and also ensures that the refName conveys portable data when exported. (Note: on export of a refName, its displayed value is fixed or "frozen" at the moment of generation and export, and thus that exported value might in the future diverge from its corresponding, dynamic value within an active deployment of a CollectionSpace system.)

If there is more than one resource part within the NSS:

• Each part is distinguished from the next by the use of a colon (":") character as a delimiter.
• The second part, and subsequent parts, if any, are hierarchical children of the parts that precede them, in a left to right ordering.

In BNF notation:

<refName> ::= "urn:" <NID> ":" <NSS>
<NID> ::= "cspace"
<NSS> :: = <NSS-namespace> ":" <resource-part> {":" <resource-part>}
<NSS-namespace> ::= <text> "." <text> {"." <text>}
<resource-part> ::= <resource-type> ":" "id" "(" <id-value> ")" ["'" <displayed-value> "'"] | <resource-type> ":" "name" "(" <short-identifier> ")" ["'" <displayed-value> "'"]
<id-value> ::= See CollectionSpace ID (CSID) for a regular expression description
<short-identifier> ::= <short-identifier-chars>
<short-identifier-chars> ::= <short-identifier-char> | <short-identifier-char> <short-identifier>
<short-identifier-char> ::= <letter> | <digit>
<displayed-value> ::= <text> | ""