search.json reference

search.json declares which of your entities are indexed for search and what of each row goes into a document. The platform builds the index from it and keeps it in step with your rows. You write no indexing code, no triggers and no crawler. For when to reach for it at all, see Projections.

The JSON Schema at https://schemas.revenexx.com/search.schema.json is the machine-readable contract. Point your editor at it; this page explains what each key means.

A complete example

The products app ships this collection (trimmed):

{
  "$schema": "https://schemas.revenexx.com/search.schema.json",
  "version": "2",
  "collections": [
    {
      "name": "products",
      "source": "products",
      "key": "id",
      "scope": { "by": ["channel", "locale"], "mode": "facet" },
      "fields": [
        { "name": "sku",             "from": "column:sku",                    "sort": true },
        { "name": "kind",            "from": "column:kind",                   "facet": true },
        { "name": "enabled",         "from": "column:enabled",                "type": "bool", "facet": true },
        { "name": "name",            "from": ["attribute:locale.name", "column:label"], "type": "string", "locale": true, "sort": true },
        { "name": "description",     "from": "attribute:locale.description",  "locale": true, "optional": true },
        { "name": "manufacturer",    "from": "attribute:common.manufacturer", "facet": true, "optional": true },
        { "name": "categories",      "from": "relation:product_categories→categories.code[]", "type": "string[]", "facet": true, "optional": true },
        { "name": "category_labels", "from": "relation:product_categories→categories.labels.<locale>[]", "type": "string[]", "locale": true, "optional": true },
        { "name": "attrs",           "from": "attribute:common.*",            "type": "object", "types_from": "attributes", "index": false, "optional": true },
        { "name": "attrs_locale",    "from": "attribute:locale.*",            "type": "object", "types_from": "attributes", "locale": true, "index": false, "optional": true },
        { "name": "updated_at",      "from": "column:updated_at",             "type": "int64", "sort": true }
      ],
      "default_sort": "updated_at",
      "depends_on": ["product_categories", "categories"]
    }
  ]
}

Top level

One app ships one search.json.

A collection

A field

Locators

from names the source of a value. You never write SQL.

The arrow is the character → (U+2192), not ->.

A list of locators

from also takes a list. The first locator that yields a value wins, in list order, so a product without a translated name still gets one:

{ "name": "name", "from": ["attribute:locale.name", "column:label"], "type": "string", "locale": true }

All locators in one list must yield the same kind of value: single values, arrays ([]) or objects. A list of single values of different types, such as a text column and a number, works only for a field of type string or auto, and the values arrive as text. A list with one locator behaves like the plain string. An empty list, or a list that mixes kinds, is refused when the app is deployed.

reference:, asset: and computed: are accepted by the schema but resolve to an empty value for now (as of 2026-10). Declare them optional if you add them early.

Locale fields

A field with "locale": true is read in the locale of the document. The platform creates one document per row and write key of the tenant, and the document's locale field says which. A tenant that keeps text per language produces de and en documents, a regional tenant de-DE and en-US. Keys no market configures are not published.

Which rows get a document in a language is the tenant's choice, not the app's. The main language (the write key of the tenant's fallback_locale) always has every row. The other languages follow the products setting search_untranslated: hide (default) publishes a row only where it has its own text in that language, fallback publishes every row and fills gaps from the main language. A fallback list in from decides what an untranslated row shows. A tenant without market locales gets one document per key that is stored. See Languages and locale codes.

A storefront asks for one locale with the X-Revenexx-Locale header and gets one hit per row back, even when a row has documents under both spellings. See Search collections.

Scope

"scope": { "by": ["channel", "locale"], "mode": "facet" }

Validation

The file is checked against the published schema when you push or publish an app version, when you validate one without publishing, and before a build starts. Unknown keys are refused, so a typo such as type_from fails instead of being ignored. The response lists each error with its path, for example collections[0].fields[1], and a build log prints them too. An invalid file fails the deployment of that version.

Version 3

Version 3 is being rolled out (as of 2026-10). Set "version": "3" to use these keys; under "2" they are refused. A version 2 file keeps working unchanged.

New locators in version 3:

What changing the file does

Add a field to the file and deploy. Existing rows are indexed in the background after the schema is applied, so results can be incomplete for a short while after a deploy. See Ship a schema change.

Where to go next

• Projections — search.json next to analytics.json, and when you need either.
• Search collections — the collections the platform ships and how to query them.
• Schema reference — the entities a collection is built from.