RefName

A refName is a structured representation for certain types of data within a CollectionSpace system. It bundles together the displayed value of that data, along with metadata about the data's context, into a parseable string.

Uses of refNames

refNames are currently used for two purposes:

• To represent references to terms in a vocabulary within an authority - Persons, Organizations, Storage Locations, Taxonomies, and Places, for instance - as well as to represent references to the vocabularies themselves.
  
  If you enter a Person or Organization into a field within a Cataloging or Procedural record, for example, the value stored will be a refName string. It will contain the displayed name of that person or organization, along with information about the vocabulary and authority to which it belongs.
  
  As well, if you identify that an authority term - a Place record, for example - has a broader context or narrower context relationship to another such record, such as a Place record for the County of Cork having a Place record for the Republic of Ireland as its broader context - the values for those hierarchical references will also be stored as refName strings, in metadata about those records.

• To represent references to object and procedural records.
  
  Beginning with CollectionSpace v2.7, some object and procedural records can have broader or narrower contexts to one another. (The specific record types that support such hierarchical relationships will vary, depending on the configuration of each individual CollectionSpace system.)
  
  If you identify that an object or procedural record - a Cataloging record, for example - has a broader context or narrower context relationship to another such record, such as a Cataloging record for a Black Rook Chess Piece having the Cataloging record for a Set of Chess Pieces as its broader context - the value stored for those hierarchical references will be stored as refName strings, in the relationship record(s) linking these two records.

In addition, refNames are stored in metadata about records, alongside other metadata such as creation and last modification timestamps for each record.

Examples

The following are representative examples of CollectionSpace refNames:

refName for a vocabulary

This refName identifies a vocabulary within a person authority, such as a vocabulary consisting of people known to the museum:

urn:cspace:core.collectionspace.org:personauthorities:name(localPersonVocabulary)'Local Person Vocabulary'

(In a similar manner, another refName might instead identify an imported vocabulary of people, such as the Getty ULAN.)

refName for a term within a vocabulary

This refName identifies a specific vocabulary term (or item), "Frederick C. Sanchez", as well as the parent vocabulary to which the term belongs, "Local Person Vocabulary", within a person authority in the demonstration core tenant:

urn:cspace:core.collectionspace.org:personauthorities:name(localPersonVocabulary):item:name(fredSanchez)'Frederick C. Sanchez'

This example, as well as the one above, uses a Short Identifier to uniquely identify the name of a specific vocabulary (localPersonVocabulary). This example also uses a Short Identifier to uniquely identify a specific term within that vocabulary (fredSanchez).

refName for a Cataloging (CollectionObject) record

Beginning with CollectionSpace version 2.7, selected types of object and procedural records can have hierarchical relationships to one another, and can also be referred to by their refNames:

urn:cspace:core.collectionspace.org:collectionobjects:id(f19a52bb-e94f-4e63-b882)'Black Rook'

In contrast to the two examples above, this example uses a CollectionSpace ID (CSID) (f19a52bb-e94f-4e63-b882) to uniquely identify the CollectionObject record. refNames can, in most cases, use either CSIDs or Short Identifiers as unique identifiers.

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.

Format of refNames

CollectionSpace refNames are structured strings. Those strings contain values, along with metadata identifying the context of these 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 (e.g. "core.collectionspace.org").
• 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 currently include "personauthorities" and "locations", and refer to authorities, which can in turn contain multiple vocabularies, each containing multiple terms.
• A colon (":") character as a delimiter.
• A resource identifier type, whose value will currently be either "name" or "item": "name" for the name of a vocabulary, or "item" for an item (term) within a vocabulary.
• An identifier of a specific instance of that resource type. This identifier is enclosed in parentheses. The identifier will either be a CollectionSpace ID (CSID) or a Short Identifier.
  • 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 - should not include a display value. Only one display value may appear, and it must be the last part of the refName string.
  • 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.)
  • This display name is also used in the fulltext indexer to recognize the use of the term in a record. If it is missing, fulltext (keyword) searches will not find records that refer to a Person, Organization, etc.
  • The displayed value may contain characters from the Unicode UTF-8 character set. See CSPACE-3717 for a discussion of whether these characters should be URL encoded.

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.

An example of a longer refName showing two resource parts, the first to identify a particular vocabulary, and the second to identify an item (term) in that vocabulary

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> ":" "name" "(" <short-identifier> ")" ["'" <displayed-value> "'"] | <resource-type> ":" "item" "(" <short-identifier> ")" ["'" <displayed-value> "'"]
<short-identifier> ::= <short-identifier-chars>
<short-identifier-chars> ::= <short-identifier-char> | <short-identifier-char> <short-identifier>
<short-identifier-char> ::= <letter> | <digit>
<displayed-value> ::= <text> | ""

See Also

• CollectionSpace ID (CSID)
• Short Identifier
• Common Services REST API documentation