Save schema by name

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.

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.