Skip to main content

Context overlays

A context overlay is a sparse set of conditional changes on top of an entity. It keeps one baseline product, campaign or piece of content while allowing selected properties to differ for a market, channel, language or customer segment.

For example, one product can have its normal campaign headline everywhere, a Swedish headline in Sweden, and a different hero image in the mobile app. Only those exceptions are stored in the overlay; every other value continues to come from the baseline entity.

Rules and precedence​

Each overridable property has an ordered list of rules. A rule contains a Boolean context expression and a replacement value. The first matching rule wins:

{
  "properties": {
    "campaignHeadline": [
      {
        "when": {
          "operator": "and",
          "operands": [
            { "operator": "equals", "contextType": "Market", "contextId": "se" },
            { "operator": "equals", "contextType": "Channel", "contextId": "app" }
          ]
        },
        "value": "Only in the Swedish app"
      },
      {
        "when": {
          "operator": "equals",
          "contextType": "Market",
          "contextId": "se"
        },
        "value": "Only in Sweden"
      }
    ]
  }
}

Expressions support equality, AND, OR and NOT. They match the exact contexts selected for the read. Context fallback belongs to VoxVarying values and is deliberately not used to make an overlay rule match implicitly.

An explicit null is a replacement value. Omitting a property means the baseline value remains in effect.

What can be overridden​

An overlay changes presentation or contextual business values; it does not change how an entity is found. Queryable, calculated and unique properties cannot be overridden because filters, sorts, search indexes and uniqueness rules must see one authoritative stored value. Relation identity is also kept in the baseline model.

This boundary makes overlays predictable: first Vox selects an entity through its normal queries and permissions, then it applies the matching contextual exceptions to the returned representation.

Use VoxVarying when a property intrinsically has a complete set of values by language, market or channel. Use an overlay when there is a useful baseline value and only some context combinations need an exception.

Editorial lifecycle​

An overlay has its own optimistic-concurrency boundary and editorial lifecycle. Editors can:

  • Save overlay changes directly to published content.
  • Prepare and preview an overlay draft independently of the baseline entity draft.
  • Add an overlay change to a content release.
  • Publish, revert or restore an earlier overlay version.
  • Resolve a conflict property by property when the published overlay changed after a draft began.

A content release publishes baseline and overlay changes atomically with the rest of its items. This makes it possible to launch a market-specific campaign together with the products, prices and content it depends on.

The Admin UI renders overlay rules from the same entity and context metadata used by the API. Another editor can build the same experience without containing knowledge of a particular Product or Campaign class.

See Languages, markets and channels, Drafts and publishing and Content releases.