Vocabulary

A vocabulary groups related taxonomy terms under one name, such as Tags, Topics or Ingredients. Technically it is a configuration entity of type taxonomy_vocabulary and the bundle of the term entity type: every term belongs to exactly one vocabulary.

How a vocabulary works in Drupal 11

The Drupal User Guide says a set of terms is known as a vocabulary. In code, the vocabulary stores five values: name, vid (its machine name), description, weight and new_revision. Weight sorts the vocabularies on the Taxonomy overview page, and new_revision is the Create new revision checkbox, which sets the default for terms in that vocabulary. In Drupal 11.4.10 the machine name is limited to 32 characters.

Because the vocabulary is the bundle, it is also the unit for three things:

• Fields. Terms get their own fields per vocabulary. Field UI hangs its field screens on the vocabulary's own page.
• Hierarchy. A term's parent field accepts only terms from the same vocabulary.
• Permissions. Core generates a set for each vocabulary: create, edit and delete terms, plus view, revert and delete term revisions.

The Standard installation profile ships one vocabulary, with the machine name tags and the description "Use tags to group content on similar topics into categories."

Example

Go to Structure › Taxonomy and choose Add vocabulary (/admin/structure/taxonomy/add). The form asks for a name, a machine name, an optional description and the Create new revision checkbox. With the Language module enabled it also shows a Term language section. Save, and Drupal opens the vocabulary's list of terms, where you can drag terms into order. The Reset to alphabetical button discards custom ordering and sorts by name.

To use the vocabulary on content, add a reference field that points at it. One reference field can allow terms from several vocabularies. When it also lets editors create new items, a Store new items in setting appears so you can pick which vocabulary receives them.

Common mistakes

• Deleting a vocabulary to clean up. Deleting removes every term in it, and the form warns that there is no undo. Unpublish or edit terms instead.
• Expecting the label to be the identifier. Code and configuration use the machine name, not the label, and the edit form locks the machine name after the first save. Pick it with care.

For marketing and content teams

A vocabulary is one controlled list: audiences, regions, product lines. Ask your site builder for one vocabulary per list, and ask which roles may edit it. Because permissions exist per vocabulary, a regional team can maintain its own list without touching the rest of the site's structure.

Sources

• Drupal User Guide: Concept: Taxonomy (checked 2026-10-26)
• Drupal User Guide: Setting up a taxonomy (checked 2026-10-26)
• Vocabulary class, Drupal API
• Drupal core 11.4.10 taxonomy module source: Vocabulary.php
• Drupal core 11.4.10 taxonomy module source: taxonomy.permissions.yml
• Drupal core 11.4.10 taxonomy module source: TaxonomyPermissions.php
• Drupal core 11.4.10 taxonomy module source: VocabularyForm.php