Morphological Analysis API Overview

The morphological analysis API is built specifically for Korean. The response is organized into three levels: sentences, word units (eojeol), and morphemes.

Sentences: the requested text is split into sentences, and each sentence is returned as a result.
Eojeol (word units): by default, eojeol follow the word spacing of the input. If you set the automatic word spacing option to true, the response rewrites the eojeol. For example, the input 아름다운강산 ("beautiful landscape") is split into 아름다운 and 강산.
Eojeol can also be joined together by the automatic joining option. A common case is a sentence with an auxiliary predicate. 떨여 졌는데 is joined into 떨어졌는데.
Morphemes are split precisely according to the 47-tag morpheme system of the National Institute of Korean Language.
Every sentence, eojeol, and morpheme carries its exact position in the original text.
There is one exception. When joining is applied and the word is also conjugated, the position cannot be represented exactly, so the output differs slightly. 굴러 먹어서 could be split into 구르+어 먹+어서, but when the joining is corrected automatically it becomes 굴러먹+어서, which makes exact positions hard to compute. Instead, the modified field is set to show that part of the original text was changed before it was recognized.

New feature (beta): distinguishing the sense of homonyms

The POS tag (NNG) cannot tell whether 다리 means a bridge (橋) or a leg (脚). When you turn on with_sense in a request, each morpheme is returned with a superscript number (the dictionary sense number) and a definition. This is a beta feature available since Bareun 3.1.0. → Homonym Sense Disambiguation API

Try It Out

Click Authorize to register your API key, then use Try it out.

Morphological Analysis Request

Request Message Definition

// Morphological analysis request message
message AnalyzeSyntaxRequest {
  // Input document
  Document document = 1;

  // Encoding type used to compute offsets
  EncodingType encoding_type = 2;

  // If auto_split_sentence is true, sentence boundaries are detected automatically.
  // Otherwise, sentences are split at \n.
  // The default is false.
  bool auto_split_sentence = 3;

  // Custom dictionary domain
  // To be removed in v4.0. Use the new custom_dict_names instead.
  // If custom_dict_names has a value, this field is ignored.
  string custom_domain = 4 [deprecated = true];

  // Automatic word spacing
  bool auto_spacing = 5;

  // Automatic word joining
  bool auto_jointing = 6;

  // Homonym sense disambiguation (WSD, beta)
  // If true, each morpheme in the response carries a sense (superscript number, definition, etc.). The default is false.
  bool with_sense = 7;

  // Custom dictionary names
  // Specify one or more dictionaries created with CustomDictionaryService.
  // If several are given, the dictionary listed first takes priority.
  repeated string custom_dict_names = 11;
}

message Document {

  // The full content of the input
  // When there are multiple sentences, separate them with "\n".
  string content = 2;

  // Language of the document. Currently only ko_KR is supported.
  string language = 4;
}

enum EncodingType {
  NONE = 0;
  UTF8 = 1;
  UTF16 = 2;
  UTF32 = 3;
}

Request Message Description

Field	Sub-field	Description
document	content	The text to analyze, which may contain several sentences. Sentences are split by default.
	language	Set to `ko_KR`. This format generally combines a language with the country where it is used. If `Bareun` ever handles the Korean used in North Korea, `ko_KP` could be used.
auto_split_sentence		Set this to `true` if you want sentence boundaries detected automatically. If `false`, sentences are split at the line feed `LF`. The Windows/DOS `CRLF` convention is not recommended.
encoding_type		`EncodingType` determines how the position of each word is computed. Suppose "안녕하세요" is split into "안녕", "하", "시", "어요". If the start position of "하" is 6, the encoding is UTF-8. If it is 2, the encoding is UTF-16 or UTF-32. Languages such as Python use `UTF32` by default. In practice it is decided by your client language. In C++, use `UTF32` with `std::wstring` and `UTF8` with plain `std::string`. Go and C++ normally use `UTF-8`, and Java uses `UTF-16`.
custom_domain		The name of a registered custom dictionary. ~~Deprecated.~~
auto_spacing		Enables word spacing correction.
auto_jointing		Enables automatic word joining correction.
with_sense		Also performs homonym sense disambiguation (WSD, beta). If `true`, each morpheme in the response carries a `sense` (superscript number, definition, Urimalsaem number, selection probability). The default is `false`. When it is off, the response and processing time are the same as before. See Homonym Sense Disambiguation API for details.
custom_dict_names		Specifies one or more dictionaries created with `CustomDictionaryService`. If several are given, the dictionary listed first takes priority.

with_sense: homonym sense disambiguation (beta)

The POS tag (NNG) cannot tell whether 다리 means a bridge (橋) or a leg (脚). When with_sense is on, the sense is chosen from context, and each morpheme is returned with a superscript number and a definition.

This feature is in beta, available since Bareun 3.1.0. During the beta it is available on api.bareun.ai (cloud). Request and response examples, accuracy, and limitations are documented in Homonym Sense Disambiguation API.

encoding_type

The encoding type specification is borrowed from Google's Natural Language API. When a client has to display the original text of a token after the call, the position values are very important. Because positions change depending on the encoding, it is better for the server to return them consistently. UTF16 covers only 65,535 Unicode code points, so recent emoji and some Chinese characters fall outside that range. As a result, UTF16 and UTF32 do not always return the same result.

custom_dict_names

You can define one or more custom dictionaries when running morphological analysis. You can define several dictionaries for different tasks and choose among them per request. Words registered in a custom dictionary can be analyzed differently.

When you specify several dictionaries in one call, they are applied in the order given, starting with the first.

Morphological Analysis Without Post-processing (AnalyzeSyntaxRaw)

AnalyzeSyntaxRaw returns the inference results of the seg and tag models as they are, with no post-processing. Unlike the regular AnalyzeSyntax, it does not apply the following.

Compound noun decomposition (e.g. 국가정보원 → 국가/NNG+정보/NNG+원/NNG)
Compound verb decomposition (e.g. 달려가다 → 달려/VV+가/VX+다/EF)
Automatic word spacing and joining
Custom dictionaries

Only auto_split_sentence works; there are no other options.

When should you use it?

To evaluate the model itself (to see pure model output with no post-processing)
To re-tag a large corpus such as BigKinds
For pipelines that control downstream processing such as WSD (word sense disambiguation) themselves

Request Message Definition

// Request message for pure morphological analysis without post-processing
message AnalyzeSyntaxRawRequest {
  // Input document
  Document document = 1;

  // Encoding type used to compute offsets
  EncodingType encoding_type = 2;

  // If auto_split_sentence is true, sentence boundaries are detected automatically.
  // Otherwise, sentences are split at \n.
  // The default is false.
  bool auto_split_sentence = 3;

  // Homonym sense disambiguation (WSD, beta). The sense is also returned exactly as the model outputs it, with no post-processing.
  bool with_sense = 4;
}

Request Message Description

Field	Description
document	The document object containing the text to analyze.
encoding_type	The encoding used to compute offsets (position and length) in the result. `UTF32` is typical for Python, `UTF8` for Go and C++, and `UTF16` for Java.
auto_split_sentence	If `true`, sentence boundaries are detected automatically. The default is `false` (split at line breaks).
with_sense	Also performs homonym sense disambiguation (WSD, beta). It has the same meaning and cost as the same option in `AnalyzeSyntax`, except that here the sense is also returned exactly as the model outputs it, with no post-processing. The default is `false`.

No custom dictionary or word spacing options

AnalyzeSyntaxRaw exists to guarantee pure model output, so it does not provide the custom_dict_names, auto_spacing, or auto_jointing fields.

Response Message

The response format of AnalyzeSyntaxRaw is the same as AnalyzeSyntaxResponse. You can use the sentences, language, and tokens_count fields as they are.

Morphological Analysis Request (No Sentence Splitting)

If you do not want sentence splitting, use the AnalyzeSyntaxList API, which returns the input sentences as they are. It is useful when you send a long text in several requests and want to track the order of the input sentences and the positions of eojeol within the text.

It is the same as the morphological analysis request above, except that the request takes an array of strings instead of a single string.
The auto_split_sentence field is not included.

Request Message Definition


// Morphological analysis request message
message AnalyzeSyntaxListRequest {
  // Array of input sentences
  repeated string sentences = 1;
  // Language of the input sentences
  string language = 2;

  // Encoding type used to compute offsets
  EncodingType encoding_type = 3;

  // Custom dictionary domain
  // To be removed in v4.0. Use the new custom_dict_names instead.
  // If custom_dict_names has a value, this field is ignored.
  string custom_domain = 4 [deprecated = true];

  // Automatic word spacing
  bool auto_spacing = 5;

  // Automatic word joining
  bool auto_jointing = 6;

  // Homonym sense disambiguation (WSD, beta)
  bool with_sense = 7;

  // Custom dictionary names
  // Specify one or more dictionaries created with CustomDictionaryService.
  // If several are given, the dictionary listed first takes priority.
  repeated string custom_dict_names = 11;
}

Request Message Description

Field	Description
sentences	The text to analyze, as an array.
language	Set to `ko_KR`. This format generally combines a language with the country where it is used. If `Bareun` ever handles the Korean used in North Korea, `ko_KP` could be used.
encoding_type	`EncodingType` determines how the position of each word is computed. Suppose "안녕하세요" is split into "안녕", "하", "시", "어요". If the start position of "하" is 6, the encoding is UTF-8. If it is 2, the encoding is UTF-16 or UTF-32. Languages such as Python use `UTF32` by default. In practice it is decided by your client language. In C++, use `UTF32` with `std::wstring` and `UTF8` with plain `std::string`. Go and C++ normally use UTF-8, and Java uses UTF-16.
custom_domain	The name of a registered custom dictionary. ~~Deprecated.~~
auto_spacing	Enables word spacing correction.
auto_jointing	Enables automatic word joining correction.
with_sense	Also performs homonym sense disambiguation (WSD, beta). The default is `false`.
custom_dict_names	Specifies one or more dictionaries created with `CustomDictionaryService`. If several are given, the dictionary listed first takes priority.

Morphological Analysis Response

Response Message Definition

message AnalyzeSyntaxResponse {
  repeated Sentence sentences = 1;
  string language = 3;
  // Number of eojeol
  int32 tokens_count = 100;
}

// A sentence analyzed from the input document
message Sentence {
  // The sentence text.
  TextSpan text = 1;

  // The sentence split into eojeol
  repeated Token tokens = 2;

  // The result after correcting word spacing errors and the like
  string refined = 3;
}


message Token {
  TextSpan text = 1;
  repeated Morpheme morphemes = 2;
  string lemma = 4;
  string tagged = 5;
  string modified = 11;
}

// A single homonym sense disambiguation (WSD, beta) result. Carried in Morpheme.sense.
message Sense {
  // Homograph number. The Urimalsaem sense number that separates homonyms with the same spelling (e.g. 1, 5, 7).
  uint32 sense_no = 1;
  // Korean definition. May be empty if Urimalsaem has no headword for it.
  string meaning = 2;
  // Unique Urimalsaem headword ID. 0 means not assigned.
  int32 urimal_target_id = 3;
  // Probability that this sense was chosen among the candidate senses [0, 1].
  float probability = 6;
}

// Morpheme
message Morpheme {
  // The sentence text.
  TextSpan text = 1;
  // Morpheme tag
  Tag tag = 2;
  // Probability of the morphological analysis result
  float probability = 3;

  // Marks words that are not in the vocabulary
  OutOfVocab out_of_vocab = 5;

  // Homonym sense disambiguation (WSD, beta) result.
  // Present only when the request has with_sense=true and a sense was assigned to this morpheme.
  // If the field is absent, no sense was assigned (it is never attached to particles, endings, and the like).
  optional Sense sense = 7;

  // How a word outside the vocabulary was handled
  enum OutOfVocab {
    IN_WORD_EMBEDDING = 0;  // Contained in the word embedding
    OUT_OF_VOCAB = 1;       // Automatically guessed; out-of-vocabulary word
    IN_CUSTOM_DICT = 2;     // Found in the user-provided dictionary
    IN_BUILTIN_DICT = 3;    // Contained in the built-in dictionary
    IN_URIMALSAEM = 4;      // Contained in Urimalsaem
    IN_WIKI_DICT = 5;       // Contained in the Wikipedia dictionary
    IN_ON_DICT = 6;         // Contained in the Onterm dictionary
  }

  // Name of the custom dictionary that was used
  optional string custom_dict_name = 6;

  // Internally the predicted morphemes are returned as 0 to 46,
  // but they are written as 1 to 47, and UNK is converted to 0.
  enum Tag {
    //// 0 1 EC
    //// 1 2 EF
    //// 2 3 EP
    //// 3 4 ETM
    //// 4 5 ETN
    //// 5 6 IC
    //// 6 7 JC
    //// 7 8 JKB
    //// 8 9 JKC
    //// 9 10 JKG
    //// 10 11 JKO
    //// 11 12 JKQ
    //// 12 13 JKS
    //// 13 14 JKV
    //// 14 15 JX
    //// 15 16 MAG
    //// 16 17 MAJ
    //// 17 18 MMA
    //// 18 19 MMD
    //// 19 20 MMN
    //// 20 21 NA
    //// 21 22 NF
    //// 22 23 NNB
    //// 23 24 NNG
    //// 24 25 NNP
    //// 25 26 NP
    //// 26 27 NR
    //// 27 28 NV
    //// 28 29 SE
    //// 29 30 SF
    //// 30 31 SH
    //// 31 32 SL
    //// 32 33 SN
    //// 33 34 SO
    //// 34 35 SP
    //// 35 36 SS
    //// 36 37 SW
    //// 37 38 VA
    //// 38 39 VCN
    //// 39 40 VCP
    //// 40 41 VV
    //// 41 42 VX
    //// 42 43 XPN
    //// 43 44 XR
    //// 44 45 XSA
    //// 45 46 XSN
    //// 46 47 XSV
    UNK = 0;
    NNG = 24; // General noun
    NNP = 25; // Proper noun
    NNB = 23; // Bound noun
    NP = 26; // Pronoun
    NR = 27; // Numeral
    NF = 22; // Presumed noun category
    NA = 21; // Unanalyzable category
    NV = 28; // Presumed predicate category
    VV = 41; // Verb
    VA = 38; // Adjective
    VX = 42; // Auxiliary predicate
    VCP = 40; // Positive copula
    VCN = 39; // Negative copula
    MMA = 18; // Qualitative determiner
    MMD = 19; // Demonstrative determiner
    MMN = 20; // Numeral determiner
    MAG = 16; // General adverb
    MAJ = 17; // Conjunctive adverb
    IC = 6; // Interjection
    JKS = 13; // Subject case particle
    JKC = 9; // Complement case particle
    JKG = 10; // Adnominal case particle
    JKO = 11; // Object case particle
    JKB = 8; // Adverbial case particle
    JKV = 14; // Vocative case particle
    JKQ = 12; // Quotative case particle
    JX = 15; // Auxiliary particle
    JC = 7; // Conjunctive particle
    EP = 3; // Pre-final ending
    EF = 2; // Sentence-final ending
    EC = 1; // Connective ending
    ETN = 5; // Nominalizing ending
    ETM = 4; // Adnominalizing ending
    XPN = 43; // Noun prefix
    XSN = 46; // Noun-derivational suffix
    XSV = 47; // Verb-derivational suffix
    XSA = 45; // Adjective-derivational suffix
    XR = 44; // Root
    SF = 30; // Period, question mark, exclamation mark
    SP = 35; // Comma, middle dot, colon, slash
    SS = 36; // Quotation marks, brackets, dash
    SE = 29; // Ellipsis
    SO = 34; // Hyphen-type marks (tilde, hidden, omitted)
    SW = 37; // Other symbols (logical/mathematical, currency)
    SL = 32; // Foreign word
    SH = 31; // Chinese character
    SN = 33; // Number
  }
}

// Text fragment
message TextSpan {
  // Content of the text fragment
  string content = 1;

  // Position of the text fragment
  // The value depends on the EncodingType.
  int32 begin_offset = 2;

  // Length
  int32 length = 3;
}

Structure of Sentences, Eojeol, and Morphemes

An analysis result is organized as follows. A sentence is an array of eojeol, and an eojeol is an array of morphemes. Each block is represented by a unit called TextSpan, which holds a finely cut piece of the string together with its position and length.

    classDiagram
        Sentence *-- Token
        Token *-- Morpheme
        Sentence *-- TextSpan
        Token *-- TextSpan
        Morpheme *-- TextSpan
        class Sentence {
            list~Token~ tokens
            TextSpan text
            String refined
        }
        class Token {
            list~Morpheme~ morphemes
            TextSpan text
            Strin glemma
            String tagged
            String modified
        }
        class Morpheme {
            tag
            probability
            outOfVocab
        }
        class TextSpan {
            String content
            int beginOffset
            int length
        }

Morphological Analysis Result

우리 모두는   늘 꿈을 꾸고 조금씩 만들어 가는 하루를 쌓아간다.

The sentence above (roughly, "Each of us keeps dreaming and piling up days that we build little by little") is analyzed as follows. Note that the input contains three spaces between 모두는 and 늘.

{
  "sentences": [
    {
      "text": {
        "content": "우리 모두는   늘 꿈을 꾸고 조금씩 만들어 가는 하루를 쌓아간다.",
        "beginOffset": 0,
        "length": 37
      },
      "tokens": [
        {
          "text": {
            "content": "우리",
            "beginOffset": 0,
            "length": 2
          },
          "morphemes": [
            {
              "text": {
                "content": "우리",
                "beginOffset": 0,
                "length": 2
              },
              "tag": "NP",
              "probability": 0.983755946,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "우리",
          "tagged": "우리/NP"
        },
        {
          "text": {
            "content": "모두는",
            "beginOffset": 3,
            "length": 3
          },
          "morphemes": [
            {
              "text": {
                "content": "모두",
                "beginOffset": 3,
                "length": 2
              },
              "tag": "NNG",
              "probability": 0.978339255,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "는",
                "beginOffset": 5,
                "length": 1
              },
              "tag": "JX",
              "probability": 0.99596709,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "모두",
          "tagged": "모두/NNG+는/JX"
        },
        {
          "text": {
            "content": "늘",
            "beginOffset": 9,
            "length": 1
          },
          "morphemes": [
            {
              "text": {
                "content": "늘",
                "beginOffset": 9,
                "length": 1
              },
              "tag": "MAG",
              "probability": 0.990521491,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "늘",
          "tagged": "늘/MAG"
        },
        {
          "text": {
            "content": "꿈을",
            "beginOffset": 11,
            "length": 2
          },
          "morphemes": [
            {
              "text": {
                "content": "꿈",
                "beginOffset": 11,
                "length": 1
              },
              "tag": "NNG",
              "probability": 0.978667676,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "을",
                "beginOffset": 12,
                "length": 1
              },
              "tag": "JKO",
              "probability": 0.998493552,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "꿈",
          "tagged": "꿈/NNG+을/JKO"
        },
        {
          "text": {
            "content": "꾸고",
            "beginOffset": 14,
            "length": 2
          },
          "morphemes": [
            {
              "text": {
                "content": "꾸",
                "beginOffset": 14,
                "length": 1
              },
              "tag": "VV",
              "probability": 0.979055166,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "고",
                "beginOffset": 15,
                "length": 1
              },
              "tag": "EC",
              "probability": 0.98225385,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "꾸",
          "tagged": "꾸/VV+고/EC"
        },
        {
          "text": {
            "content": "조금씩",
            "beginOffset": 17,
            "length": 3
          },
          "morphemes": [
            {
              "text": {
                "content": "조금",
                "beginOffset": 17,
                "length": 2
              },
              "tag": "NNG",
              "probability": 0.976339459,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "씩",
                "beginOffset": 19,
                "length": 1
              },
              "tag": "XSN",
              "probability": 0.954161286,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "조금",
          "tagged": "조금/NNG+씩/XSN"
        },
        {
          "text": {
            "content": "만들어",
            "beginOffset": 21,
            "length": 3
          },
          "morphemes": [
            {
              "text": {
                "content": "만들",
                "beginOffset": 21,
                "length": 2
              },
              "tag": "VV",
              "probability": 0.976726532,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "어",
                "beginOffset": 23,
                "length": 1
              },
              "tag": "EC",
              "probability": 0.984725058,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "만들",
          "tagged": "만들/VV+어/EC"
        },
        {
          "text": {
            "content": "가는",
            "beginOffset": 25,
            "length": 2
          },
          "morphemes": [
            {
              "text": {
                "content": "가",
                "beginOffset": 25,
                "length": 1
              },
              "tag": "VX",
              "probability": 0.766881585,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "는",
                "beginOffset": 26,
                "length": 1
              },
              "tag": "ETM",
              "probability": 0.997791588,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "가",
          "tagged": "가/VX+는/ETM"
        },
        {
          "text": {
            "content": "하루를",
            "beginOffset": 28,
            "length": 3
          },
          "morphemes": [
            {
              "text": {
                "content": "하루",
                "beginOffset": 28,
                "length": 2
              },
              "tag": "NNG",
              "probability": 0.983489573,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "를",
                "beginOffset": 30,
                "length": 1
              },
              "tag": "JKO",
              "probability": 0.99864924,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "하루",
          "tagged": "하루/NNG+를/JKO"
        },
        {
          "text": {
            "content": "쌓아",
            "beginOffset": 32,
            "length": 2
          },
          "morphemes": [
            {
              "text": {
                "content": "쌓",
                "beginOffset": 32,
                "length": 1
              },
              "tag": "VV",
              "probability": 0.96607554,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "아",
                "beginOffset": 33,
                "length": 1
              },
              "tag": "EC",
              "probability": 0.990258396,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "쌓",
          "tagged": "쌓/VV+아/EC"
        },
        {
          "text": {
            "content": "간다.",
            "beginOffset": 34,
            "length": 3
          },
          "morphemes": [
            {
              "text": {
                "content": "가",
                "beginOffset": 34,
                "length": 1
              },
              "tag": "VX",
              "probability": 0.790500104,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": "ㄴ다",
                "beginOffset": 34,
                "length": 2
              },
              "tag": "EF",
              "probability": 0.983418167,
              "outOfVocab": "IN_WORD_EMBEDDING"
            },
            {
              "text": {
                "content": ".",
                "beginOffset": 36,
                "length": 1
              },
              "tag": "SF",
              "probability": 0.996877491,
              "outOfVocab": "IN_WORD_EMBEDDING"
            }
          ],
          "lemma": "가",
          "tagged": "가/VX+ㄴ다/EF+./SF"
        }
      ],
      "refined": "우리 모두는 늘 꿈을 꾸고 조금씩 만들어 가는 하루를 쌓아 간다."
    }
  ],
  "language": "ko_KR"
}

Morpheme Object

The morpheme object looks like this.

// Morpheme
message Morpheme {
  // The sentence text.
  TextSpan text = 1;
  // Morpheme tag
  Tag tag = 2;
  // Probability of the morphological analysis result
  float probability = 3;

  // Marks words that are not in the vocabulary
  OutOfVocab out_of_vocab = 5;

  // Name of the custom dictionary that was used
  optional string custom_dict_name = 6;

  // Homonym sense disambiguation (WSD, beta) result. Present only on morphemes that were assigned one.
  optional Sense sense = 7;

  // How a word outside the vocabulary was handled
  enum OutOfVocab {
    IN_WORD_EMBEDDING = 0;  // Contained in the word embedding
    OUT_OF_VOCAB = 1;       // Automatically guessed; out-of-vocabulary word
    IN_CUSTOM_DICT = 2;     // Found in the user-provided dictionary
    IN_BUILTIN_DICT = 3;    // Contained in the built-in dictionary
    IN_URIMALSAEM = 4;      // Contained in Urimalsaem
    IN_WIKI_DICT = 5;       // Contained in the Wikipedia dictionary
    IN_ON_DICT = 6;         // Contained in the Onterm dictionary
  }
}

Field	Sub-field	Description
text	content	The content of the segmented form.
	begin_offset	The start position of the segmented form. When conjugation, contraction, or omission has occurred, the restored form points to the position of the original syllable.
	length	The length of the segmented form.
tag		See the POS tag table below.
probability		The score the deep learning engine computed for the tagging. A larger value means the POS is more likely. It is not a probability distribution that sums to 1 over the POS candidates, so do not add it to other candidates' values or compare it against a threshold such as `sense.probability`.
out_of_vocab		The basis on which this word was guessed.
custom_dict_name		A request can refer to one or more dictionaries, so you may need to check which dictionary a word was chosen from. This returns the name of the dictionary that was used.
sense	sense_no	The superscript number (the sense number in Urimalsaem) from the homonym sense disambiguation (WSD, beta) result. `sense` is returned only when the request turned on `with_sense` and a sense was assigned to this morpheme.
	meaning	The Korean definition. May be empty if Urimalsaem has no headword for it.
	urimal_target_id	The unique Urimalsaem headword ID. You can open the dictionary page at `https://opendict.korean.go.kr/dictionary/view?sense_no=<value>`.
	probability	The probability that this sense was chosen among the candidate senses of that word. Over all candidates it sums to 1, and it is always 1.0 when there is only one candidate.

Homonym Sense (sense): Beta

The same 다리 (NNG) is analyzed with different senses depending on context. When you turn on with_sense in the request, sense is returned as shown below.

{
  "text": { "content": "다리", "beginOffset": 0, "length": 2 },
  "tag": "NNG",
  "probability": 0.9917928,
  "outOfVocab": "IN_WORD_EMBEDDING",
  "sense": {
    "senseNo": 5,
    "meaning": "물을 건너거나 또는 한편의 높은 곳에서 다른 편의 높은 곳으로 건너다닐 수 있도록 만든 시설물.",
    "urimalTargetId": 836,
    "probability": 0.935963
  }
}

(The meaning value is the Korean Urimalsaem definition: "A structure built so that one can cross water, or cross from a high place on one side to a high place on the other.")

A morpheme without sense is normal

sense is returned only on morphemes that were assigned a sense. When there is none, the key does not appear in the response at all. It is never attached to particles, endings, or symbols, and it is absent in every call that did not turn on with_sense. So decide by whether the key exists, not by comparing values.

The beta notes, accuracy and limitations, and per-language examples are collected in Homonym Sense Disambiguation API.

Words Not Seen in Training

Words that were not seen during training are a constant problem in deep learning NLP. Bareun can automatically extract such words, especially newly coined ones.

enum	Value	Description
IN_WORD_EMBEDDING	0	A value used in training.
OUT_OF_VOCAB	1	An out-of-vocabulary word. Its POS is assigned by automatic guessing.
IN_CUSTOM_DICT	2	The word was found in a custom dictionary. Use `custom_dict_name` to look up the name of the dictionary that was applied.
IN_BUILTIN_DICT	3	The word was found in the built-in dictionary.
IN_URIMALSAEM	4	The word was found in the Urimalsaem dictionary. (Shown by the spell checker)
IN_WIKI_DICT	5	The word was found in the Wikipedia dictionary. (Shown by the spell checker)
IN_ON_DICT	6	The word was found in the Onterm dictionary. (Shown by the spell checker)

Values 4 to 6 appear in the spell checker

IN_URIMALSAEM, IN_WIKI_DICT, and IN_ON_DICT (4 to 6) are dictionaries used by the spell checker (the correction feature). When you use only the morphological analyzer, you normally get values 0 to 3, and these three values do not appear.