Search Config Properties: Synonyms – Yext Help

Synonyms tell Search which words and phrases to consider as having the same meaning. Search has three types of synonyms: one-way synonyms, synonym sets, and normalization synonyms.

Search Configuration Schema

Within the Search configuration, the synonyms object defines the configuration settings for synonyms. Refer to the table below for the available fields. View where synonyms fits into the configuration in the Search Config Properties - Top Level doc.

Property	Type	Shown in Config UI	Description
`oneWay`	array of objects	Yes	A phrase that, when detected, is expanded to include all of the synonyms associated with the phrase.
`synonymSet`	array of arrays of strings	Yes	A collection of phrases that, whenever any is present in a user’s query, is expanded to include all other terms in the set.
`normalization`	array of objects	Yes	A collection of phrases that, whenever any is present in a user’s query, is expanded to include one synonym associated with the phrases.

Top-Level JSON

The JSON below is for demonstrative purposes only to show the structure of the synonyms object through the top-level properties. Find more detail about each below.

"synonyms": {
  "oneWay": [],
  "synonymSet": [],
  "normalization": []
},

One Way Synonyms

One-way synonyms look for a phrase and expands it to include all of the synonyms associated with the phrase. The oneWay property is an array of objects, where each object is a separate synonym with the following properties:

Property	Type	Shown in Config UI	Description
`phrase`	string	Yes	The text used in a query that will be replaced with matching synonyms
`synonyms`	array of strings	Yes	The list of terms that the query should be expanded with

The following is an example of two sets of one-way synonyms:

“order online” will be expanded with “delivery”
“career” will be expanded with “job” and “apply”

"synonyms": {
"oneWay": [
  {
    "phrase": "order online",
    "synonyms": [
      "delivery"
    ]
  },
  {
    "phrase": "career",
    "synonyms": [
      "job",
      "apply"
    ]
  }
],
}

Synonym Sets

Synonym sets expand phrases to include all the other terms in the set. It is an array of arrays. Each array represents a separate set in the synonymSet property.

For example, this synonym set specifies “doctor”, “healthcare professional”, and “physician” are all equivalent to each other:

"synonyms": {
  "synonymSet": [
    [
      "doctor",
      "healthcare professional",
      "physician"
    ]
  ],
}

Normalization Synonyms

Normalization synonyms are the exact inverse of a one-way synonym, where a set of many terms is mapped to one term. These are particularly useful when multiple search terms can be used to reference the same thing. Use the normalization property to specify them.

Property	Type	Shown in Config UI	Description
`from`	array of strings	Yes	The list of terms that should be replaced with matching synonyms, what you’re mapping from.
`to`	string	Yes	The term that the query should be replaced with, what the multiple terms will normalize to.

For example, the terms “rewards”, “points”, and “membership” will all normalize to “gift card” below. This could be useful if we have content on gift cards, but not the other terms in particular. We don’t want them to return no results and “gift card” is close enough content.

"synonyms": {
  "normalization": [
    {
      "from": [
        "rewards",
        "points",
        "membership"
      ],
      "to": "gift card"
    }
  ]
}