Compatibility policy

This page is a reference. It answers two questions: how a renderer decides whether it understands a document, and what it does with every part it does not understand. The answers are fixed by the contract; a renderer does not choose its own.

Who needs it:

• An app developer — the first three sections: what your users see when a document is newer than the app, and how to move between major versions.
• Someone writing or auditing a renderer — the policy tables and the checklist at the end.

Related pages: index · quickstart for Flutter · iOS · Android · theme · localization · widgets · changelog · quickstart for React

Why there is a policy#

The builder and the app are released separately. A manager can publish a screen built with a newer contract than the app in a user's pocket understands. That is the normal case for server-driven UI, not an error.

The policy is machine-readable. It lives in the artifacts under x-compatibility, so a renderer can test itself against it instead of trusting a document like this one. The keys and values below are copied from the artifacts.

The contracts and their versions#

Where the artifact files are published is said in the overview.

The versions are independent. A rebrand adds no widgets and a new widget changes no palette. One shared number would force a release of everything on every change of one part.

What they share is the rule below, not the number. 9.0.0 says nothing about 4.0.0: the two became major versions on the same day for two different reasons.

Changing values does not change a version. A new value for a color, a new token of your own in the theme, or a new field in a project's data dictionary, is content. A version changes when the structure changes.

How a renderer decides#

A version is three numbers: major.minor.patch. Nothing else is accepted — no prefixes, no pre-release suffixes.

Compare the document's version with the version your renderer was written for:

The patch number never affects the decision.

The rule rests on one promise: a minor version only adds optional things. A renderer of an older minor therefore knows everything that is required in the document.

The two version keys are identical in the schema and the theme artifacts:

How each renderer package exposes the rule:

To the contract a newer and an older major are the same mismatch. The packages tell them apart only to choose what to say to the user: "update the app" helps with a newer document and never with an older one, which has to be published again from the builder.

final verdict = document.versionVerdict;
if (!verdict.canRender) {
  // show your own message; "update the app" is true only for VersionVerdict.newerMajor
}

A major mismatch is the only case in which the user must be told something. An empty screen reads as a broken app, not as an outdated one.

A document and a theme fail differently#

Moving from 8 to 9#

Widget schema 9.0.0 and theme 4.0.0 are major versions, so the first row of the table above applies to every app in the field.

What changed. The look of a node — padding, background, radius, border, shadow, color, text style — moved out of props into style, which is now the same on every widget. A style field accepts a token or a value of the document's own. The theme declares its own token names next to a required core. The list of moved fields is in the changelog.

What happens to documents.

• A published 8.x document stays 8.x until it is published again. Nothing rewrites published files. The builder migrates a draft when a manager opens it; the manager then publishes, and the published file becomes 9.x.
• An app with a renderer of 8.x does not draw a 9.x document. There is no partial drawing: a 9.x document read as 8.x would be a screen with no backgrounds and no padding.
• A migrated document looks the same. The migration moves fields and writes down the defaults that 8.x renderers applied silently. It invents nothing.
• The theme has its own major. A renderer of theme 3.x rejects a 4.x theme as a whole and draws with its fallback theme; a 4.x renderer does the same with a 3.x theme. The screen is drawn either way, in fallback colors, and the renderer reports it.

The order that leaves no user without a screen.

1. Keep every published version on your backend, or keep the 8.x file at its address. Apps in the field ask for 8.x for as long as they are not updated.
2. Publish each document again from the builder. Serve the 9.x version to renderers that ask for 9.x and the last 8.x version to renderers that ask for 8.x — the rule is in the backend guide.
3. Publish the theme again; it becomes 4.0.0. Serve 3.x to renderers of 3.x in the same way.
4. Replace the document and the theme bundled in the app with their 9.x and 4.x forms, then release the app with the 9.x renderer. A bundled 8.x copy in a 9.x app is a fallback that cannot be drawn.

If your app reads the published files directly from our storage, there is one file per document, and it holds the last publication. Publishing again replaces the 8.x file with a 9.x one, and apps with an 8.x renderer fall back to their bundled copy from that moment. Release the app update first in that setup, or serve documents through your own backend.

Two majors cannot be served side by side from the direct address. Side-by-side delivery needs the webhook and your own backend.

Widget schema policy#

x-compatibility.policy in screen-schema.json.

What "unknown token" means since 9.0.0#

Before 9.0.0 the schema held a closed list of token names, and an unknown token was a name from a newer minor. The list is gone: the theme declares the names. An unknown token is now a name the theme you are drawing with does not declare — it was removed from the project theme, or one theme of the set lacks a name another has.

The builder does not publish such a document. A renderer still has to know what to do with one:

Never substitute a similar token. An invented color looks like a correct one.

A renderer therefore needs the theme itself at render time, not only its values: whether a token exists is a question to the theme.

Order of two rules#

unknownVisibilityOp is stronger than missingConditionValue.

A node with an unknown operator stays visible even when the data is missing. The two cases are different: a missing value means "I know the question and have no answer"; an unknown operator means "I do not know the question". Check that the operator is one you know before you look at the value.

Why a missing value counts as empty#

One rule for all operators would apply to an operator and to its negation alike. On a screen without data both halves of a branch — "the list" and "nothing here yet" — would disappear.

"Empty" is the only question that absence answers. An absent flag is neither true nor false.

Check a list by its length, not by its text: an empty collection is empty.

Catalogs of what appeared when#

x-compatibility has two more maps. They let a renderer tell "from a newer version" from "broken document".

widgets — widget type → the schema version it appeared in.

features — a capability that is not a widget → the schema version it appeared in.

The three 9.0.0 entries are there for the record, not for degradation: 9.0.0 is a major version, and a renderer of 8.x does not open a 9.x document at all.

How to use them with an unknown widget type:

The Flutter renderer mirrors the maps as kWidgetCatalog and kFeatureCatalog, and classifies with widgetOriginOf(type) and supportsFeature(name). In debug builds it draws a labelled placeholder around an unknown widget; in release builds only the children are shown.

What each version added, and what an older renderer loses, is in the changelog.

Other blocks of the schema artifact#

x-budget — the weight of one document.

x-mirroredIcons — the icon names that mirror in a right-to-left script: 29 names since 9.3.0 (chevron, arrow-left, arrow-right, chevron-left, chevron-right, log-out, send, undo, …). Read the list from the artifact. See localization.

x-icons — { "drawings": "contract/icons.json", "names": "IconToken" } (since 9.3.0): where the drawings of the icons are, and which list of the schema names them.

x-template (since 9.4.0) — the limits and parameters of text templates as data: the pattern of a value name and the maximum number of values, the plural categories, the keys translations are stored under, the parameters of the number and currency formats (grouping, fraction digits, the separator before the currency code and its code point), the length of a day and the rounding of daysUntil, which formats give a number a plural can agree with, and where the shared table of cases is (fixtures/template/template-cases.json). See data dictionary.

The icon set#

icons.json is a separate artifact with a version of its own, iconSetVersion (currently 1.0.0). A redrawn icon is a patch of the set and does not touch the schema; a new name is a minor of the set and of the schema. A renderer embeds the set and draws every icon from it — it keeps no pictures of its own.

currentColor is the foreground color of the node. A drawing never carries a color of its own. The size of an icon did not change: see iconGlyphBox below.

x-tokens — the shape of a token name, the limit of custom names per dictionary, the core names every theme has, and zeroScale: the token none in spacing, radius and elevation is always zero by the structure of a theme (token: "none", sets: ["spacing", "radius", "elevation"]). x-style — how a node's style is read: states, inheritance, the box model, widgets with a role. Both are written out in words in the widget reference.

x-style keys added after the first 9.0.0 draft, each one a decision a renderer would otherwise make alone:

x-style.layout — lists, so that a policy word is not a request to invent a list:

x-actions — the action catalog (since 9.8.0): executors, catalog (the type of each named action, who performs it, its parameters with name, required, form, bindable), forms (httpsUrl and appLink with their pattern, maxLength and, for an app link, schemePattern and forbiddenSchemes), problems and problemOrder, paramBinding, handed (the fields of the action the host gets), track (the form and the limits of an analytics event), carryRecord, cases. The rule in words is the policy keys from standardActionExecution to actionTrack, carryRecord, and the four refinements before release (unbindableParamBinding, keyAutoRepeat, stackScreenGone, actionParamComposition); params gives the form of a literal parameter (keyPattern, keyMaxLength, valueMaxLength, valueType, reservedNames, invalidEntry).

x-screenShown — the screen-shown event (since 9.8.0): causes, transitions (what each change of the stack means), fields, and what entry, depth and record are. The rule in words is screenShown, screenShownOnBack and screenShownOnServer.

x-dataScope — the data layers of a screen (since 9.2.0). The rule in words is the eight policy keys from actionRecord to pickedChoice.

x-schemaVersion — the version of the artifact. x-generatedFrom — a note that the file is generated.

Theme contract policy#

x-compatibility.policy in theme.json.

Theme 4.0.0 removed its own unknownToken key: a name outside the core is now normal, not "from the future". Both artifacts say the same words about gradients: gradientStopOrder: 'non-descending' and unorderedGradient: 'do-not-draw'. A gradient of the theme and a custom gradient of a document are treated alike: not drawn when the stops go backwards.

x-rules — seven rules the embedded schema cannot express: every theme of a set declares the same token names; a role names a color that exists; a token a document names is declared by the project theme. The builder enforces them; the policy above says what a renderer does when a theme from elsewhere breaks one.

x-optionalColors — the fallback map for the optional state colors:

The whole theme contract, the fallback levels and the load statuses are on the theme page.

Data dictionary delivery rules#

x-delivery in data-contract.json.

The renderers do not read the data dictionary at run time, and they do not check x-dataContractVersion. A document is self-sufficient: it names its own paths, fallbacks and formats. The dictionary is the agreement between the builder and your backend. See data dictionary and the backend guide.

Checklist for a renderer#

• The version is checked first; another major is refused and the user is told.
• A newer minor is drawn.
• An unknown widget draws its children and does not throw.
• A document of 8.x is refused by a 9.x renderer, and the bundled fallback copy is already 9.x.
• Token names come from the theme: a theme with a token of its own draws it.
• A token the theme does not declare takes the field default in props; in style the property is not applied, and an inherited color or text style stays.
• A node without style has no background and no padding.
• A state replaces a style field as a whole; color and typography are inherited after the state is applied.
• A button with a style.background keeps the label color of its role.
• An unknown action reaches the host app.
• An unknown condition operator leaves the node visible — also when the data is missing.
• A missing value makes isEmpty hold and nothing else.
• A missing translation shows the source text.
• An unknown entry point opens the initial screen.
• An unreadable theme falls back, and the host can see that it did.
• A state with an undeclared token keeps the base field; a size outside its own range is clamped; a non-number literal takes the lower bound of the field.
• fill outside a direct layer of a Stack is ignored; Tabs.initialTab out of range opens the first visible tab.
• The lists in x-style.layout are read from the artifact, not remembered.
• none is zero in spacing, radius and elevation; a partial theme is completed from the built-in theme of the same brightness.
• A document deeper than 32 levels is refused before parsing; an own __proto__ key is dropped as an entry and the screen is still drawn.
• In a column a card, a text and an image are stretched; a button that is not full-width, a badge, an icon and a progress ring keep their natural width and follow the align of the column (check align: center).
• A nested row with weights beside a weighted sibling neither crashes nor divides anything: its children take their natural width.
• opacity: null does not hide a node; weight: 0 does not collapse it; a shadow layer without an offset has a zero offset.