Vocabularies

Many fields hold values from a DDEX allowed-value set: roles (MainArtist), resource types (MusicalWorkSoundRecording), territories (US), commercial models. These queries let a client offer the real values instead of a free-text box.

Values are stored and returned exactly as delivered — never case-folded or normalized. Values a sender used that DDEX does not define are kept and marked ddexDefined: false. See DDEX vocabularies.

Operations

queryvocabValues
queryvocabKindIsClosed

The VocabValue object#

One value of a DDEX vocabulary.

Attributes

valueString!
The value exactly as DDEX (or the sender) spells it.
ddexDefinedBoolean!
true if DDEX defines it; false if it was seen in a delivery but is not in the DDEX set.

List vocabulary values#

queryvocabValues→[VocabValue!]!catalog_read

The values of one vocabulary. Vocabularies change only when DDEX publishes a new revision, so fetch a whole kind once and filter locally; the limit is high enough for the largest set.

Arguments

kindString!required
The vocabulary, e.g. DisplayArtistRole, ResourceContributorRole, ImageType, CurrentTerritoryCode.
searchString
Case-insensitive substring filter. Omit for every value.
limitInt!Default: 50
Maximum number of values. Clamped to 1–1000.

Returns

A list of VocabValue objects. An unknown kind returns an empty list.

Request

query {
  vocabValues(kind: "DisplayArtistRole", search: "artist") {
    value
    ddexDefined
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  vocabValues(kind: \"DisplayArtistRole\", search: \"artist\") {\n    value\n    ddexDefined\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        vocabValues(kind: "DisplayArtistRole", search: "artist") {
          value
          ddexDefined
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "vocabValues": [
      { "value": "FeaturedArtist", "ddexDefined": true },
      { "value": "MainArtist", "ddexDefined": true }
    ]
  }
}

Check whether a vocabulary is closed#

queryvocabKindIsClosed→Boolean!catalog_read

Whether DDEX enumerates this vocabulary. For a closed kind, show a picker of vocabValues; for an open one (genres, language codes) allow free text as well.

Arguments

kindString!required
The vocabulary to check.

Returns

A Boolean.

Request

query {
  vocabKindIsClosed(kind: "ImageType")
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  vocabKindIsClosed(kind: \"ImageType\")\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        vocabKindIsClosed(kind: "ImageType")
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "vocabKindIsClosed": true
  }
}