Theme Data Structure — Schema Reference

Updated: 2026-08-29 · Status: reconciled against the shipped Mobile Content API (AB#2609)

ThemeDto field schema

A theme is a single, independent row — not a node in an inheritance chain. The Dynamic Feed guide and the Admin Portal guide document slightly different field sets for the same underlying row (read-side vs. write/manage-side); both are shown below. See Theme Token Inheritance Model for why the cascading ThemeNode schema previously documented here was never built.

Theme assignment: Site and Page

There is no tier below Page — an LEC is itself a Page (same as before), but it has no special theming behavior beyond the ordinary Page-level activeThemeId override described above. There is no scopeType/scopeKey concept; Site and Page are identified by their own native keys (siteKey, pageKey).

Container / Item token references

Container and Item content records do not carry a merged override dictionary. Instead, each carries its own set of individual *Token fields that reference a token path by name — the value is resolved from whichever theme is active for that Page at render time:

This is the real analog of what earlier revisions of this doc modeled as a single structured themeTokenOverrides dictionary merged at resolution time. The actual shape is the reverse of that description: most overrides are individual, per-field, direct token-path references (not a merged bag), and only Items get one additional free-form JSON override field (tokenOverrides) for ad hoc cases — Containers don't have an equivalent free-form field.

Worked example: UAL hierarchy

Two independent theme rows, a Site assignment, and a Page-level full-swap override:

There is no walk/merge step: resolving a Page's effective theme is "does this Page have a non-null activeThemeId? If yes, fetch that theme. If no, fetch the Site's activeThemeId instead." — a single conditional, not a chain.

A Container and Item under this Page layer their own token references on top of whichever theme resolved above (see Container / Item token references):

Canonical token catalog

Tokens — the registry, not the values

Tokens is a separate, simpler structure from everything above — it doesn't belong to any one theme or scope. It's the flat list of which token keys are allowed to exist at all, and how they're grouped:

Tokens (the registry) answers "what tokens exist"; ThemeDto.tokens (the field, on any individual theme) answers "what value does this theme give every one of them." Because there is no inheritance between themes, every ThemeDto must provide a value for every Tokens registry entry — there's no partial or sparse theme. Tokens itself carries no values — it's schema, not data — so it changes far less often than any individual theme does, and is enforced server-side via the Admin API's POST /theme/validate-tokens endpoint (admin-portal.html).

The token subset already known from earlier examples in this doc set, grouped by category, comparing the ALPA base value against the UAL theme's value for each. This is illustrative, not the full 95-token registry (see the warning above).

Surface

Text

Border

Icon

Action

Nav

Status

Font

Spacing

BorderRadius

See also

• Theme Token Inheritance Model — the narrative account of the cascading model that was proposed here and not built, and what shipped instead.
• Theme Model — Future Extensibility — extension points for the (never-built) cascade proposal; largely superseded by the same reconciliation.
• Mobile Admin Portal — Integration Guide — the authoritative source for the real ThemeDto, token registry, and typography endpoints.
• Dynamic Feed — Integration Guide — the authoritative source for how Site/Page resolve their active theme.