Brief Description

For a full description, visit the Service Description and Assumptions page.

Assumptions

For a complete list of assumptions, visit the Service Description and Assumptions page.

References

Vocabulary and Authority Overview
Vocabulary Service Description and Assumptions
Vocabulary Service Entity Diagrams

REST-based API

The Vocabulary Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Vocabulary instances, and on the associated VocabularyItem instances. These follow the Common model for CollectionSpace REST services.

Note that the VocabularyItem instances are not directly "addressible"; they can only be accessed via the parent Vocabulary.

• Vocabulary CRUD+L services
• Vocabulary REST payload schemas
• VocabularyItem CRUD+L services
• VocabularyItem REST payload schemas

Vocabulary CRUD+L services

Create a Vocabulary

Creates a new Vocabulary record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Vocabulary record. Follows standard Create model. See the documentation of the Vocabulary schema, below. Example:

Read a Vocabulary

Reads an existing Vocabulary record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Vocabulary schema, below.

General form:

Example, reading an existing record with a CSID of e450e8e8-9f12-49f3-aba4-43b7c46344a2:

An alternate form reads an existing Vocabulary record, specified by its short identifier, which matches the value of the shortIdentifier field in the record. Otherwise follows standard Read model. See the documentation of the Vocabulary schema, below.

General form:

Example, reading an existing record with a shortIdentifier value of myDefaultVocabulary:

Update a Vocabulary

Updates an existing Vocabulary record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Vocabulary schema, below. Example:

Delete a Vocabulary

Deletes an existing Vocabulary record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

List Vocabulary instances

Lists existing Vocabulary records, with summary information for each. Follows standard List model. See the documentation of the Vocabulary-List schema, below.

Examples:

List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:

List also supports query parameters for searching for matching records, including keyword search. For example:

Vocabulary REST payload schemas

Vocabulary instance schema

Create and Update should use the following schema. The value of vocabType must be "enum".

Validation constraints: Values for shortIdentifier must be non-null and may only include word characters ("a-zA-Z0-9_"), or call will return 400 Bad Request.

Read will return the above, plus additional fields (uri and csid) for access:

Vocabulary-List schema

List (and variants) will return the following schema. Note the standard pagination support.

VocabularyItem CRUD+L services

VocabularyItem instances are only accessible via the owning Vocabulary. The sub-resource is accessed with "items" (this is consistent across all vocabulary-like services). In the examples below, the {vocabulary-id} parameter represents an identifier (such as a CSID value) of an existing Vocabulary instance.

Create a VocabularyItem in a Vocabulary

Creates a new VocabularyItem record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that VocabularyItem record. Follows standard Create model. See the documentation of the VocabularyItem schema, below. Example:

Read a VocabularyItem in a Vocabulary

Reads an existing VocabularyItem record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the VocabularyItem schema, below. Example:

Update a VocabularyItem in a Vocabulary

Updates an existing VocabularyItem record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the VocabularyItem schema, below. Example:

Delete a VocabularyItem in a Vocabulary

Deletes an existing VocabularyItem record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

List VocabularyItem instances in a Vocabulary

Lists existing VocabularyItem records, with summary information for each. Follows standard List model. The vocabulary may be specified either using the CSID or the shortIdentifier, using the syntax described for vocabulary read, described above. See the documentation of the VocabularyItem-List schema, below.

Examples:

List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:

List also supports query parameters for searching for matching records, including:

• keyword search
• partial term matching search, for term completion
• term status filtering, to exclude (filter out) records matching one or more statuses

For example:

VocabularyItem REST payload schemas

VocabularyItem instance schema

Create and Update should use the following schema. The value of inVocabulary must match the parent vocabulary, and must not be modified once the instance is created.

Validation constraints: On create and update, displayName must be non-null and at least 2 characters long, or call will return 400 Bad Request. Values for shortIdentifier must be non-null and may only include word characters ("a-zA-Z0-9_").

Note: You might need to wrap some of the payload in <document> tags, e.g.,

Read will return the above, plus additional fields (uri and csid) for access:

VocabularyItem-List schema

List (and variants) will return the following schema. Note the standard pagination support.