The five custom dictionaries at a glance: when to use which

A Bareun custom dictionary is not just "a place to register words the analyzer doesn't know." The dictionary a word goes in depends on whether it is a proper noun, a compound noun, or a verb, and which dictionary you choose changes the part of speech (POS) and tokenization in the morphological analysis result.

This document summarizes the purpose of the five custom dictionaries (NP/CP/CP^/VV/VA) at a glance and gives selection criteria for answering the question, "Which dictionary should this word go in?"

Table of the five custom dictionaries

One custom dictionary (domain) consists of the following five sets (DictSet). Each set is recognized as a different POS in the morphological analysis result.

Dictionary field	Name	Recognized POS	Purpose	Examples
`np_set`	Proper noun (NP)	NNP	Unique names of people, places, products, events, and so on	`크리스토퍼놀란`, `걸어서세계속으로`, `민식이법`
`cp_set`	Compound noun (CP)	NNG	A new coinage or technical term, made of several nouns, that has fixed into one unit	`코로나19`, `바나나우유`, `압수수색`
`cp_caret_set`	Split compound noun (CP^)	NNG + NNG	Tokenized as two separate words even when written together	`형태소^분석`, `디지털^인문학`, `데이터^산업`
`vv_set`	Verb (VV)	VV	New verbs, recognized including inflected forms	`카톡하다`, `맑내하다`
`va_set`	Adjective (VA)	VA	New adjectives, recognized including inflected forms	`소녀스럽다`, `신박하다`, `판타스틱하다`

Why are there five dictionaries?

In Korean, the same characters can be a noun or a predicate (verb or adjective) depending on context. Bareun takes your POS intent clearly at registration time and tags according to that intent when analyzing. For example, if you put 카톡하다 in the verb dictionary, it recognizes even inflected forms such as "카톡했다" and "카톡하는" as verbs, but if you put it in the noun dictionary, it does not. Above all, even for a word it doesn't know, Bareun can guess whether it is a predicate or a nominal, and that guess is very accurate. When an out-of-vocabulary word appears where a predicate belongs, it looks through the verb and adjective dictionaries. That is why Bareun keeps separate dictionaries for each POS.

Criteria for choosing the dictionary

Following the flow below, you can find the right place for most words.

graph TD
  A[Word to register] --> B{Is it a predicate?};
  B -- Verb --> VV[vv_set: verb];
  B -- Adjective --> VA[va_set: adjective];
  B -- Noun --> C{Is it a unique name?};
  C -- Yes: person, product, law --> NP[np_set: proper noun];
  C -- No: general concept --> D{Treat as one unit<br>or split in two?};
  D -- As one word --> CP[cp_set: compound noun];
  D -- Split into two words --> CPC[cp_caret_set: split compound noun];

If it is a name, use NP: A one-of-a-kind name such as a company, product, person, or law is a proper noun (np_set). It is tagged NNP in the result.
If it is a fixed unit, use CP: A new coinage or technical term that has fixed into one word in meaning, such as 코로나19, goes in the compound noun set (cp_set) and is recognized as a single NNG as a whole.
If you want to split it for search or indexing, use CP^: For a word that cannot be searched when recognized as one unit, mark the split point with ^ in the split compound noun set (cp_caret_set), as in 형태소^분석.
If it conjugates, use VV/VA: A new coinage that ends in "~하다/~스럽다" and conjugates must go in the verb or adjective dictionary to be recognized in forms like "했다, 하는, 스러운".

Group dictionaries into domains

One set of the five is one domain. Create separate domains for each area, such as law, medicine, and finance, and pick the domains you need with custom_dict_names when analyzing. A domain name may contain only letters, digits, _, and -.

Custom dictionaries are separated by API key

Custom dictionaries are stored separately for each API key (user) issued. Even on the same Bareun server, different API keys have different sets of dictionaries.

A dictionary registered with an API key is applied only when you analyze or correct with that key. It is not visible to requests made with other keys.
When you list registered dictionaries, only the domains registered under your own key appear.
The limit on the number of domains is also applied per API key.

For this reason, if a domain you put in custom_dict_names has no effect, first check whether that domain is registered under the API key you are currently using. A dictionary registered with key A cannot be used by requests made with key B. If your team uses several keys, you must register the dictionary separately for each key that uses it.

The same applies in MCP

The MCP bareun://custom-dicts resource also returns the list of registered dictionaries based on the API key used in the call. In other words, each key sees a different set of dictionaries.

Checking the registration result

You can check whether a registered word came from the custom dictionary by seeing whether the morpheme's out_of_vocab value is IN_CUSTOM_DICT. The domain it came from is in custom_dict_name.

크리스토퍼놀란/NNP, IN_CUSTOM_DICT
코로나19/NNG, IN_CUSTOM_DICT
카톡하/VV, IN_CUSTOM_DICT

Frequently asked questions

No. Custom dictionaries are separated by the API key issued to you. A dictionary registered with a key applies only when you analyze or correct with that key, and listing shows only your own key's dictionaries. To use the same dictionary with several keys, register it separately for each key. (The MCP bareun://custom-dicts resource is also based on the calling key.)

Q. Can I put the same word in several dictionaries?

We don't recommend it. If the same headword is in several of NP/CP/CP^/VV/VA at once, it is reported as a conflict. Check with CheckConflict before registering. See the conflict check document for details.

Q. What is the difference between a compound noun (CP) and a split compound noun (CP^)?

CP bundles the whole as a single noun (NNG), like 코로나19, while CP^ splits it into two or more nouns, like 형태소^분석. If word-level indexing matters, as in search and RAG, use CP^.

Q. Do I need to restart the server when I change a dictionary?

No. Bareun detects dictionary file changes in real time and applies them without downtime. See the document on instant, zero-downtime updates for details.

Q. How do I manage custom dictionaries? Can I edit a text file directly?

Manage custom dictionaries through the CustomDictionaryService API (UpdateCustomDictionary, and so on). The server stores custom dictionaries in its own (binary) format, so you do not edit the files in the dictionary directory by hand. If you need version control, keep your own word-list source in Git and apply it through the API.

Q. How do I check whether a registered word came from the custom dictionary?

Check whether the morpheme's out_of_vocab value is IN_CUSTOM_DICT. The domain it came from is in custom_dict_name, so you can check the source and POS together, as in 크리스토퍼놀란/NNP, IN_CUSTOM_DICT.