diff --git a/specs/search/paths/dictionaries/batchDictionaryEntries.yml b/specs/search/paths/dictionaries/batchDictionaryEntries.yml index a3c35b98ed6..02451362f18 100644 --- a/specs/search/paths/dictionaries/batchDictionaryEntries.yml +++ b/specs/search/paths/dictionaries/batchDictionaryEntries.yml @@ -2,7 +2,7 @@ post: tags: - Dictionaries operationId: batchDictionaryEntries - description: Send a batch of dictionary entries. + description: Add or remove a batch of dictionary entries. summary: Batch dictionary entries. parameters: - $ref: 'common/parameters.yml#/DictionaryName' @@ -12,7 +12,8 @@ post: application/json: schema: title: batchDictionaryEntriesParams - description: The `batchDictionaryEntries` parameters. + description: > + `batchDictionaryEntries` parameters. type: object required: - requests @@ -21,10 +22,10 @@ post: clearExistingDictionaryEntries: type: boolean default: false - description: When `true`, start the batch by removing all the custom entries from the dictionary. + description: If `true`, delete all custom entries in the dictionary and then add the ones sent with this request. requests: type: array - description: List of operations to batch. Each operation is described by an `action` and a `body`. + description: Operations to batch. items: title: batchDictionaryEntriesRequest type: object diff --git a/specs/search/paths/dictionaries/common/parameters.yml b/specs/search/paths/dictionaries/common/parameters.yml index dba15e24ade..14ca1984531 100644 --- a/specs/search/paths/dictionaries/common/parameters.yml +++ b/specs/search/paths/dictionaries/common/parameters.yml @@ -2,7 +2,7 @@ DictionaryName: in: path name: dictionaryName - description: The dictionary to search in. + description: Dictionary to search in. required: true schema: $ref: '#/dictionaryType' @@ -13,12 +13,14 @@ dictionaryType: # misc language: - description: Language ISO code supported by the dictionary (e.g., "en" for English). + description: > + [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/). + example: 'en' type: string standardEntries: - description: Map of language ISO code supported by the dictionary (e.g., "en" for English) to a boolean value. - type: object + description: > + Maps a [supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) to a boolean value (for example, `'fr': false`). If `true` Algolia's built-in [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/) for that language have been turned off. additionalProperties: false properties: plurals: @@ -29,7 +31,9 @@ standardEntries: $ref: '#/standardEntry' standardEntry: - description: Language ISO code. + description: Language ISO code and boolean. + example: > + {'fr': false} type: object nullable: true additionalProperties: diff --git a/specs/search/paths/dictionaries/common/schemas/Languages.yml b/specs/search/paths/dictionaries/common/schemas/Languages.yml index 4a6fdd31e40..cfa8350b29b 100644 --- a/specs/search/paths/dictionaries/common/schemas/Languages.yml +++ b/specs/search/paths/dictionaries/common/schemas/Languages.yml @@ -1,6 +1,6 @@ languages: type: object - description: A dictionary language. + description: Dictionary language. additionalProperties: false required: - plurals @@ -20,6 +20,9 @@ dictionaryLanguage: nullable: true description: Custom entries for a dictionary. properties: - nbCustomEntires: - description: "When nbCustomEntries is set to 0, the user didn't customize the dictionary. The dictionary is still supported with standard, Algolia-provided entries." + nbCustomEntries: + description: > + If `0`, the dictionary hasn't been customized and only contains standard entries provided by Algolia. + + If `null`, that feature isn't available or isn't supported for that language. type: integer diff --git a/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml b/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml index 6f9b89f29a2..1243706610f 100644 --- a/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml +++ b/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml @@ -16,28 +16,51 @@ searchDictionaryEntriesResponse: dictionaryEntry: type: object - description: A dictionary entry. + description: Dictionary entry. additionalProperties: true required: - objectID - language properties: objectID: - $ref: '../../../../../common/parameters.yml#/objectID' + type: string + description: Unique identifier for a dictionary object. + example: 'under' language: type: string - description: Language ISO code supported by the dictionary (e.g., "en" for English). + description: > + [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/). + example: 'de' word: type: string - description: The word of the dictionary entry. + description: > + Dictionary entry word. Usage depends on the type of dictionary entry. + + **`stopwordEntry`** + + The stop word you want to add or update. If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`. + + **`compoundEntry`** + + When `decomposition` is empty: adds `word` as a compound atom. + For example, atom “kino” decomposes the query “kopfkino” into "kopf" and "kino". + + When `decomposition` isn't empty: creates a decomposition exception. + For example, when decomposition is set to the ["hund", "hutte"] exception, "hundehutte" decomposes into “hund” and “hutte”, discarding the linking "e". + example: 'down' words: type: array - description: The words of the dictionary entry. + description: > + Compound dictionary [word declensions](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/). + + If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`. + example: ['cheval','chevaux'] items: type: string decomposition: type: array - description: A decomposition of the word of the dictionary entry. + description: For compound entries, governs the behavior of the `word` parameter. + example: ['kopf','schmerz','tablette'] items: type: string state: diff --git a/specs/search/paths/dictionaries/dictionarySettings.yml b/specs/search/paths/dictionaries/dictionarySettings.yml index e9959319162..3b383575fbf 100644 --- a/specs/search/paths/dictionaries/dictionarySettings.yml +++ b/specs/search/paths/dictionaries/dictionarySettings.yml @@ -2,8 +2,8 @@ get: tags: - Dictionaries operationId: getDictionarySettings - description: Retrieve dictionaries settings. The API stores languages whose standard entries are disabled. Fetch settings does not return false values. - summary: Retrieve dictionaries settings. + description: Get the languages for which [stop words are turned off](#tag/Dictionaries/operation/setDictionarySettings). + summary: Get stop word settings. responses: '200': description: OK @@ -31,8 +31,8 @@ put: tags: - Dictionaries operationId: setDictionarySettings - description: Set dictionaries settings. - summary: Set dictionaries settings. + description: Set stop word settings for a specific language. + summary: Set stop word settings. requestBody: required: true content: @@ -41,7 +41,7 @@ put: title: dictionarySettingsParams type: object additionalProperties: false - description: Disable the builtin Algolia entries for a type of dictionary per language. + description: Enable or turn off the built-in Algolia stop words for a specific language. required: - disableStandardEntries properties: diff --git a/specs/search/paths/dictionaries/getDictionaryLanguages.yml b/specs/search/paths/dictionaries/getDictionaryLanguages.yml index 4d8abb6e305..1152bccd5d5 100644 --- a/specs/search/paths/dictionaries/getDictionaryLanguages.yml +++ b/specs/search/paths/dictionaries/getDictionaryLanguages.yml @@ -2,7 +2,7 @@ get: tags: - Dictionaries operationId: getDictionaryLanguages - description: List dictionaries supported per language. + description: Lists Algolia's [supported languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) and any customizations applied to each language's [stop word](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plural](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), and [segmentation (compound)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) features. summary: List available languages. responses: '200': diff --git a/specs/search/paths/dictionaries/searchDictionaryEntries.yml b/specs/search/paths/dictionaries/searchDictionaryEntries.yml index 853f2e6acc8..604635f8d49 100644 --- a/specs/search/paths/dictionaries/searchDictionaryEntries.yml +++ b/specs/search/paths/dictionaries/searchDictionaryEntries.yml @@ -4,8 +4,8 @@ post: operationId: searchDictionaryEntries x-use-read-transporter: true x-cacheable: true - description: Search the dictionary entries. - summary: Search a dictionary entries. + description: Search for standard and [custom](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/) entries in the [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plurals](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), or [segmentation (compounds)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) dictionaries. + summary: Search dictionary entries. parameters: - $ref: 'common/parameters.yml#/DictionaryName' requestBody: @@ -14,7 +14,8 @@ post: application/json: schema: title: searchDictionaryEntriesParams - description: The `searchDictionaryEntries` parameters. + description: > + `searchDictionaryEntries` parameters. type: object required: - query