> For the complete documentation index, see [llms.txt](https://docs.vale.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vale.sh/keys/vocabularies.md).

# Vocabularies

Learn about Vale's terminology management system.

Vocabularies allow you to maintain custom lists of terminology independent of your styles.

```ini
StylesPath = "..."

# Here's were we define the exceptions to use in *all*
# `BasedOnStyles`.
Vocab = Some-Name

[*]
# 'Vale' and 'MyStyle' automatically respect all
# custom exceptions.
#
# The built-in 'Vale' style is required for using
# `Vale.Terms`, `Vale.Avoid`, or `Vale.Spelling`.
BasedOnStyles = Vale, MyStyle
```

Each `Vocab` is a single folder (stored at `<StylesPath>/config/vocabularies/<name>/`) consisting of two plain-text files—`accept.txt` and `reject.txt`—that contain one regular expression per line.

The effects of using a custom `Vocab` are as follows:

* Entries in `accept.txt` are added to every exception list in all styles listed in `BasedOnStyles`—meaning that you now only need to update your project’s *vocabulary* to customize third-party styles.
* Entries in `accept.txt` are automatically added to a substitution rule (`Vale.Terms`), ensuring that any occurrences of these words or phrases exactly match their corresponding entry in `accept.txt`.
* Entries in `reject.txt` are automatically added to an existence rule (`Vale.Avoid`) that will flag all occurrences as errors.
* Entries in `accept.txt` and `reject.txt` should need little overlap, if any. For example, if you add `JavaScript` to `accept.txt`, then you do not need to add an overlapping regular expression entry of `[Jj]avascript` in `reject.txt`. Vale will enforce correct casing by virtue of the entry’s presence in `accept.txt`. See the section “Case sensitivity” for details.

This means that your exceptions can be developed independent of a style, allowing you to use the same exceptions with multiple styles or switch styles without having to re-implement them.

{% hint style="warning" %}
In versions of Vale prior to 3.0, vocabularies were stored in `<StylesPath>/Vocab`. When upgrading from an older version of Vale, you'll need to move your vocabularies to the new `<StylesPath>/config/vocabularies` location.
{% endhint %}

Vocabulary entries are stored in `<StylesPath>/config/vocabularies/<name>/` and are then referenced by `<name>` in `.vale.ini`. For example, consider the following folder structure:

```
$ tree styles
├───MyStyle
├───config
│   └───vocabularies
│       ├───Blog
│       │   ├───accept.txt
│       │   └───reject.txt
│       └───Marketing
│           ├───accept.txt
│           └───reject.txt
└───MyOtherStyle
```

Here, our `StylesPath` (`/styles`) contains two styles (`MyStyle` and `MyOtherStyle`) and two vocabularies (`Blog` and `Marketing`). You can then reference these entries by their folder name:

```ini
StylesPath = styles

Vocab = Blog

[*]
BasedOnStyles = Vale, MyStyle
```

## Vocabularies for a section

{% hint style="info" %}
Requires Vale v3.22.0 or later.
{% endhint %}

A section can name a vocabulary of its own, for the files it matches:

```ini
StylesPath = styles
Vocab = Product

[*]
BasedOnStyles = Vale

[api/*.md]
Vocab = API
```

Under `api/`, the accepted terms of `API` are added to those of `Product`; elsewhere only `Product` applies. Several matching sections add up. A section's vocabulary gets rules of its own, `Vale.API.Terms` and `Vale.API.Avoid`, which run only on that section's files and can be switched off by name like any other rule.

A vocabulary named in `[*]` applies to every file, with rules of its own that are on everywhere; this is how a [package](/keys/packages.md#a-vocabulary) turns on the vocabulary it carries.

`Vocab = NONE` clears the vocabularies named before it at the same level: at the top of the file, the top-level ones from earlier configuration layers, such as a package's; in a section, that section's.

## File format

Both `accept.txt` and `reject.txt` are plain-text files that take one entry per line:

```
first
[pP]y.*\b
third
```

The entries are evaluated as case-sensitive (except for rules extending `spelling`, as mentioned above) regular expressions, with two allowances for how terms are written. A period is text, not a wildcard, unless the entry uses some other regular-expression construct, so `Node.js` accepts `Node.js` and nothing else. And the space in a phrase matches a line break as well, so `mea culpa` is found where a paragraph wraps between the two words.

A line beginning with `#` and a space is a comment and is ignored; `#tag` on its own is an entry.

An alert from `Vale.Terms` offers the entry's spelling as a [fix](/topics/actions.md) when it is plain text, and the terms are candidates when a `spelling` rule [suggests](/fixes/suggest.md#spellings) a correction, ahead of the dictionary's own words.

## Case sensitivity

An important factor in successfully implementing a custom vocabulary is understanding how Vale handles case sensitivity.

While most spell-checking tools ignore case altogether, Vale’s vocabulary files are case-aware by default. This means that, for example, a vocabulary consisting of

```
MongoDB
```

will enforce the *exact* use of “MongoDB”: “mongoDB,” “MongoDb,” etc., will all result in errors. There are two ways around this.

First, you can indicate that a given entry should be case-insensitive by providing an appropriate regular expression:

```
(?i)MongoDB
[Oo]bservability
```

The first entry, `(?i)MongoDB`, marks the entire pattern as case-insensitive while the second, `[Oo]bservability`, provides two acceptable options.

You can also disable `Vale.Terms` and just use `Vale.Spelling`:

```ini
[*.md]
BasedOnStyles = Vale

Vale.Terms = NO
```

This will provide a more traditional spell-checking experience.

## Dictionaries and vocabularies

A [dictionary](/checks/spelling.md#dictionaries) and a vocabulary answer different questions:

|               | Dictionary                                                                      | Vocabulary                                              |
| ------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Answers       | Is this a word?                                                                 | How do we write it here?                                |
| Case          | Permissive: a lower-case entry also accepts its capitalized and all-caps forms. | Exact: `Vale.Terms` reports any other case, with a fix. |
| Rejects terms | No                                                                              | Yes, with `Vale.Avoid`                                  |
| Read by       | `spelling` rules                                                                | Every rule in `BasedOnStyles`, as exceptions            |
| Maintained by | Vale, or the dictionary's publisher                                             | Your project                                            |

Put ordinary words, including technical ones like `failover` or `namespace`, in a dictionary or let the built-in one cover them. Put names and terms with a required spelling, like `PostgreSQL` or your product's name, in a vocabulary: it accepts them, enforces their case, and offers the fix.

## Relation to ignore files

The functionality of vocabularies is similar to the existing concept of [ignore files](/checks/spelling.md#ignore-files).

The major differences are that vocabularies apply to multiple extension points (rather than just `spelling`), support regular expressions, and have built-in rules associated with them (`Vale.Terms` and `Vale.Avoid`).

In general, this means that ignore files are for style *creators* while vocabularies are for style *users*:

* If you’re developing or maintaining a style, you may still want to include a custom `spelling` rule—`MyStyle.Spelling`—that packages its own ignore files.
* As a user of styles, vocabularies should be able to replace the use of ignore files completely.

## Rules targeting vocabulary entries

In cases where you want to write a rule that needs to match against an otherwise-ignored token, you can add `vocab: false` to the rule definition. For example,

```yaml
extends: existence
message: Did you mean '%s'?
vocab: false
tokens:
  # "MonoDB" can be in a vocab
  - MongoDB
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.vale.sh/keys/vocabularies.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.