Creates or edits a data entity schema. Learn more about Master Data schemas.

Note that if you send a schemaName that does not exist for that data entity, this request will create it.

This request can also be used to create or edit Master Data v2 triggers.

Each Master Data v2 data entity can have up to 60 schemas.

Indexing fields for search, scroll and sort

To filter or sort by a field in Search documents or Scroll documents, add that field to the v-indexed array in the schema. This is the schema-level index (separate from the indices endpoint).

• v-indexed: Array of property names that Master Data v2 must index for /search, /scroll, and _sort. Use it whenever you want to use _where, _sort, or range filters (e.g. _where=postalCode between 10000 AND 20000) on that field. Indexing runs asynchronously after the schema is saved.
• filterable and searchable: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do not create the index used by /search; only v-indexed does.

Example request body with v-indexed:

{
  "properties": {
    "skuId": { "type": "string" },
    "postalCode": { "type": "string" }
  },
  "v-indexed": ["postalCode"]
}

ℹ️ Use v-indexed when you need fields to be filterable/sortable in /search. Use the /indices endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.

Reindex lock

Saving a schema can trigger a full reindex of the data entity. The reindex lock works in two stages:

1. Locking the data entity: The lock starts only when a schema save triggers a reindex. Schema saves that don't trigger a reindex never lock the data entity.
2. While the lock is active: Every later schema save for that same data entity is rejected with 423 Locked, including saves that would not trigger a reindex on their own. The response states that the reindex is still in progress.

A schema save can trigger a new reindex of the same data entity only after an interval of 12 hours. Don't calculate a retry time from this interval. To know when the data entity accepts schema saves again, read the Message field of the 423 Locked response, which states the time after which you can retry. When that time is not available, the message asks you to try again later.

Permissions

Any user or API key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code 403 error. These are the applicable resources for this endpoint:

There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see Authentication overview.

❗ To prevent integrations from having excessive permissions, consider the best practices for managing API keys when assigning License Manager roles to integrations.