Getting started
Getting started
Everything an app, a theme or an integration ships is a declared file, and every one of those files is validated against a schema on this host. Four steps get you from an empty repo to a deployment that passes.
Four steps
Pick what you are building
An app, a theme or an integration needs a different set of files. Each category page lists exactly the contracts for that thing, in the order they matter, and links to the guide on the developer portal.
Point your file at its schema
Add $schema as the first key. Your editor reads the URL straight from this host and validates and completes the file while you type, in VS Code, JetBrains and anything else that follows a $schema URL.
Read the contract while you write it
Every schema on this host has a page: the fields at the root, the shapes they point at, the rules across fields, and the file itself. Each field carries a link you can send to a colleague.
Deploy
Console validates your deployment against these files live and reports the first thing that disagrees. The file it reads is the file you read here, so what your editor accepted is what the gate accepts.
What you are building
Each of these lists the contracts for one kind of extension, what each one does for it, and where the guide on the developer portal starts.
The one line to add
This is the whole setup. From here your editor knows every key, every enum value and every required field in the contract.
{
"$schema": "https://schemas.revenexx.com/manifest.schema.json",
"vendor": "acme",
"name": "products",
"version": "1.0.0"
}Swap the file name for whichever contract you are writing. The table below has all of them.
How this works
What this host is
The canonical JSON Schemas for the revenexx App contract. Console validates every App deployment against these files, the platform build worker validates against them, and any editor that follows a $schema URL reads them directly.
Every consumer reads them from here, live. The file you fetch this morning is the file your deployment is measured against this afternoon, on one source of truth that stays in step with the platform.
Point a file at its schema
Each schema validates the file of the same name in your app repo: manifest.schema.json validates manifest.json. Add $schema as the first key and your editor gives you validation and autocompletion while you type.
{
"$schema": "https://schemas.revenexx.com/manifest.schema.json",
"vendor": "acme",
"name": "products"
}Operator-facing copy is localizable
Every slot that carries copy takes either a plain string or a map of BCP-47 language tag to text. en is required and is what the Cockpit falls back to, so a half-translated file still reads as English. The plain string stays valid forever.
Column names, enum values and wire prefixes stay plain strings. They are data, and they read the same in every language.
{ "label": "Products" }
{ "label": { "en": "Products", "de": "Produkte" } }Reading these pages
Each field says how many of a thing it holds: 1 for one, n for many, map for a keyed collection, which also names what the key means, e.g. map of entity name → entity.
A red dot or the required badge means the field is required. Grey chips underneath are constraints read off the file: default, pattern, format, range.
localizable text is one thing you may write two ways. Where the contract branches, each alternative carries the name of the property that selects it: a Cockpit view is a listView *when `type` is list*.
How a change reaches you
Consumers fetch live and cache for a day, and re-fetch as soon as a document fails validation. A published change therefore reaches everyone on the next rejected deployment, on its own, with no consumer deploy involved.
Which is why changes here are additive: a new required entry, a narrowed enum or a stricter pattern would retroactively reject manifests that validated an hour ago. Nearly every object in the contract sets additionalProperties: false, so every key you write is a key this contract declares, and a typo shows up as a rejection you can read.
Which file do I need?
Each schema validates the file of the same name in your app repo. Everything in this table is read off the files themselves.
| What it declares | |||
|---|---|---|---|
| Analytics | analytics.json | analytics.schema.json | Flat views over your entities, ready as datasets for reporting and BI tools, without writing SQL. |
| Billing | billing.json | billing.schema.json | What your app costs and how it appears in the marketplace: one monthly price, and the listing a customer sees. |
| Cockpit (Administration) | cockpit.json | cockpit.schema.json | Your admin screens: lists, detail views, forms and dashboards, declared in a file instead of built as an app of their own. |
| API Capabilities | manifest.capabilities.json | manifest.capabilities.schema.json | The typed API operations your app offers other apps, kept in their own file when the manifest gets long. |
| App Manifest | manifest.json | manifest.schema.json | Who your app is and what it may touch: identity, dependencies, the permissions it asks for, and the events it emits. |
| Database Schema | schema.json | schema.schema.json | The tables your app owns. Declare columns, keys and indexes once, and the platform creates and migrates them for every tenant. |
| Search | search.json | search.schema.json | What of your data is searchable: the collections, the fields and the facets, kept in sync as records change. |
| App Settings | settings.json | settings.schema.json | What an operator can configure for your app, per tenant and per market, rendered as a settings form for them. |
| Theme Events | theme-events.json | theme-events.schema.json | What your theme tells listeners happened in the shop: page views, carts, orders, with no personal data in it. |
| Theme Extension | theme-extensions.json | theme-extensions.schema.json | Blocks your theme extension adds to an existing theme without forking it, rendered on your own Site and installed per tenant. |
| Theme Preset | theme-preset.json | theme-preset.schema.json | The starter content your theme installs for a tenant: pages, menus, reusable blocks and brand settings. |
| Theme Manifest | theme.json | theme.schema.json | Who your theme is and where it is served: identity, the domains it runs on, and the capabilities it needs to work. |