SynonymDictionary Metadata Type in SFDX

Architectural Overview#

The SynonymDictionary metadata type represents the declarative configuration of search synonym groups in Salesforce Knowledge and Einstein Search. When contact center agents, service technicians, or self-service community members search knowledge bases and CRM records, they frequently use colloquial terminology, internal jargon, or acronyms that do not literally match the authored text—such as searching for “laptop” when the article references “notebook computer”, or “USB-C” when the product is cataloged as “Type-C cable”.

Architecturally, SynonymDictionary injects semantic expansion into the Salesforce SOSL (Salesforce Object Search Language) index. A synonym group contains a set of symmetrical terms and target language codes. Searching for any term within the group automatically yields search results indexed against any other term in that group. Managing synonym dictionaries in version control empowers enterprise knowledge management teams to maintain high search recall across global service operations.

Directory and File Conventions#

In SFDX source format, SynonymDictionary components reside in the synonymDictionaries directory:

Key Metadata Fields#

The SynonymDictionary XML schema structures synonym groups, languages, and terms:

Declarative XML and Package Manifest Examples#

Below is a declarative SynonymDictionary defining hardware and device terminology across English and Spanish locales:

<?xml version="1.0" encoding="UTF-8"?>
<SynonymDictionary xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>IT_Hardware_Synonyms</fullName>
    <label>IT Hardware Synonyms</label>
    <groups>
        <languages>en_US</languages>
        <terms>laptop</terms>
        <terms>notebook</terms>
        <terms>portable computer</terms>
    </groups>
    <groups>
        <languages>en_US</languages>
        <terms>headset</terms>
        <terms>headphones</terms>
        <terms>earphones</terms>
    </groups>
    <groups>
        <languages>es</languages>
        <terms>ordenador portatil</terms>
        <terms>computadora portatil</terms>
    </groups>
    <isProtected>false</isProtected>
</SynonymDictionary>

Add the component to the package manifest:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>IT_Hardware_Synonyms</members>
        <name>SynonymDictionary</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment#

Use Salesforce CLI commands to manage search dictionaries:

# Retrieve all synonym dictionaries
sf project retrieve start --metadata "SynonymDictionary:*"

# Deploy specific dictionary to production org
sf project deploy start --metadata "SynonymDictionary:IT_Hardware_Synonyms" --target-org prod

# Query synonym dictionaries via Tooling API
sf data query --query "SELECT Id, DeveloperName, MasterLabel FROM SynonymDictionary" --use-tooling-api

Senior Architect Considerations#

1. Pre-requisite Permissions: Ensure the deploying user profile or permission set has Manage Synonyms enabled and that Knowledge search is enabled in target org settings.
2. Search Index Latency: Deploying updates to SynonymDictionary metadata triggers background index recompilation. Allow several minutes post-deployment for index propagation to complete before conducting search testing.
3. Avoid Over-Expansion: Creating excessively broad synonym groups (e.g., grouping generic terms like “system”, “app”, and “software”) degrades search precision by introducing excessive noise into agent search results.

Frequently asked questions

What is the role of SynonymDictionary in Salesforce?

SynonymDictionary defines groups of interchangeable terms that Salesforce Knowledge and Einstein Search treat as identical during search queries.

Which folder stores SynonymDictionary files in SFDX?

They are stored in force-app/main/default/synonymDictionaries with the .synonymDictionary-meta.xml or .synonymDictionary file extension.

Are synonym group matches symmetric in Salesforce Search?

Yes, synonym matches are fully symmetric; searching for any term in a group returns records containing any other term in that group.

What permissions are required to deploy SynonymDictionary?

Deploying users must have the Manage Synonyms permission and synonyms must be enabled in Search Settings.