TopicsForObjects Metadata Type in SFDX & Metadata API

Why the TopicsForObjects Metadata Type Matters#

In Salesforce Lightning Experience and Experience Cloud portals, Topics allow users and automation to tag records (Case, Knowledge__kav, Account, or custom objects) with structured taxonomy tags without creating dozens of multi-select picklists. Before any user or Apex trigger can insert a TopicAssignment on an SObject—or before the standard Topics component will render on a FlexiPage—that object must have TopicsForObjects (topicsForObjects/<Object>.topicsForObjects-meta.xml) enabled.

Key Metadata Fields on TopicsForObjects#

Real-World XML Example (topicsForObjects/Knowledge__kav.topicsForObjects-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<TopicsForObjects xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableTopics>true</enableTopics>
    <entityApiName>Knowledge__kav</entityApiName>
</TopicsForObjects>

Querying Topic and TopicAssignment via SOQL#

Once TopicsForObjects is enabled, topics and record-to-topic links are stored in the standard Topic and TopicAssignment objects. Note that in Experience Cloud, each site (Network) maintains its own isolated topic namespace via NetworkId!

1. Query All Topics Assigned to a Specific Record (e.g., Case or Knowledge Article)#

SELECT Id, TopicId, Topic.Name, EntityId, EntityType, NetworkId, CreatedDate
FROM TopicAssignment
WHERE EntityId = :recordId
ORDER BY Topic.Name ASC

2. Find All Cases Tagged with a Specific Topic in Internal Org (NetworkId = null)#

SELECT Id, EntityId, EntityKeyPrefix, Topic.Name, CreatedBy.Name
FROM TopicAssignment
WHERE EntityType = 'Case'
  AND Topic.Name = 'Security Incident'
  AND NetworkId = null
ORDER BY CreatedDate DESC

Senior Architect Best Practices#

Frequently asked questions

What does the TopicsForObjects metadata type control?

TopicsForObjects enables or disables Topics for Objects on a specific standard or custom SObject (such as Account, Case, Knowledge__kav, or a custom object), allowing users to tag records with hashtags and filter lists or Experience Cloud feeds by Topic.

Why is my Lightning Topics component failing to render on a custom object record page in Production?

If you deploy a FlexiPage containing the standard Topics component (forceChatter:topicsOnRecordWrapper) without also deploying TopicsForObjects with enableTopics set to true for that object, the component cannot display or save record topics.

How do you query which Topics are assigned to a specific record using SOQL?

You query the TopicAssignment junction object filtering by EntityId (the record ID) or EntityType (the SObject name) and traverse Topic.Name to read the assigned topic names.

How are TopicsForObjects files named in SFDX source format?

Each file in force-app/main/default/topicsForObjects/ is named ObjectApiName.topicsForObjects-meta.xml, such as Case.topicsForObjects-meta.xml or Project__c.topicsForObjects-meta.xml.