Vocabularies

Vocabularies are a set of allowed choices that back a particular field. They contain so called terms which represent those allowed choices.

Concepts

Vocabularies contain a list of terms. These terms are usually tokenized, meaning that in addition to a term’s value, it also has a token which is a machine-friendly identifier for the term.

Terms can also have a title, which is intended to be the user-facing label for the term.

Vocabularies can be context-sensitive, meaning that they take the context into account and their contents may therefore change depending on the context they’re invoked on.

Listing all vocabularies

To retrieve a list of all the available vocabularies, send a GET request to the @vocabularies endpoint:

GET /@vocabularies HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

The response will include a list with the URL (@id) and the names (title) of all the available vocabularies:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:8080/@vocabularies/actions",
    "title": "actions"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/availableLanguages",
    "title": "availableLanguages"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/behaviors",
    "title": "behaviors"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/boolean",
    "title": "boolean"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/captchaProviders",
    "title": "captchaProviders"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/groups",
    "title": "groups"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/imageScales",
    "title": "imageScales"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/permissions",
    "title": "permissions"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/roles",
    "title": "roles"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/subjects",
    "title": "subjects"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/supportedLanguages",
    "title": "supportedLanguages"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/systemGroups",
    "title": "systemGroups"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/systemUsers",
    "title": "systemUsers"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/types",
    "title": "types"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/users",
    "title": "users"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/workflowStates",
    "title": "workflowStates"
  },
  {
    "@id": "http://localhost:8080/@vocabularies/workflows",
    "title": "workflows"
  }
]

Get a vocabulary

To enumerate the terms of a particular vocabulary, use the @vocabularies endpoint with the name of the vocabulary, e.g. /@vocabularies/roles. The endpoint can be used with the site root and content objects.

GET /@vocabularies/roles HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

The server will respond with a list of terms. The title is purely for display purposes. The token is what should be sent to the server to address that term.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:8080/@vocabularies/roles",
  "items": [
    {
         "title": "Administrator",
         "token": "Administrator"
     },
     {
       "title": "Anonymous",
       "token": "Anonymous"
     },
     {
       "title": "Authenticated",
       "token": "Authenticated"
     },
     {
       "title": "Contributor",
       "token": "Contributor"
     },
     {
       "title": "Editor",
       "token": "Editor"
     },
     {
       "title": "Owner",
       "token": "Owner"
     },
     {
       "title": "Reader",
       "token": "Reader"
     },
     {
       "title": "Reviewer",
       "token": "Reviewer"
     }
  ],
  "items_total": 8
}