Locale overlays

Not yet released

Locale overlay support ships in a release after API-dex 3.1.0 and is not in the current product. The Changelog lists it under Unreleased.

Locale overlays follow the OpenAPI Initiative Overlay Specification 1.x. They are stored per specification version and applied at read time. This page is lookup detail. The model is explained in Translated specifications; the publishing steps are in Translating a specification.

Overlay document

Each overlay is a YAML or JSON file with:

Field	Requirement
overlay	Version 1.x.y
info.title	Required
actions	A non-empty list
Each action	A JSONPath target plus update, remove or both

overlay: 1.0.0
info:
  title: Dutch translation
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: Nederlandse beschrijving.
  - target: $.paths['/internal']
    remove: true

Translate descriptive text only. Changing paths, operation IDs, parameter names or schema structure through an overlay makes the translated view describe a different API from the one published.

Vendor extensions such as x-description-nl-NL on the canonical specification are not read as translations. They are stored untouched as ordinary extensions.

Supported locales

en-GB, nl-NL, de-DE, fr-FR, es-ES, se-SE, ar-SA.

Resolution when a specification is read with a locale: exact match, then the primary language (nl serves nl-NL, NL-nl is normalised), then the canonical specification. An unsupported locale is rejected on write and serves the canonical specification on read. Duplicate locales in one write are rejected.

Platform API

Endpoint	Roles	Behaviour
GET /api/specs/{specId}?locale={locale}	Any signed-in user	Returns the specification with the overlay for that locale applied. Without locale, returns the canonical document
GET /spec?specid={specId}&locale={locale}	Public spec route	Same behaviour for the public specification route
GET /api/specs/{specId}/overlays	Administrator, CI/CD	Lists the stored overlays and their locales
PUT /api/specs/{specId}/overlays	Administrator, CI/CD	Upserts the locales in the body. Locales already stored and not named in the body stay unchanged
DELETE /api/specs/{specId}/overlays	Administrator, CI/CD	Removes every overlay for the specification
overlays array on the spec upload body	Administrator, CI/CD	Stores overlays together with a new specification version

Reads fail open: a broken overlay or an unreachable overlay store never fails a specification read. The canonical document is served and the problem is logged. The management endpoints report the real error.

New specification versions

Overlays belong to a specification id. A new version starts without them unless overlay files are sent again.

An upload, from the portal or from apidex-cli upload-spec, is refused when the new version would drop published translations: no overlay files, or a subset of the locales already stored. An equal or larger set of locales is accepted. --force does not bypass this check. A first upload with no overlays succeeds.

apidex-cli validate --require-locales is a separate, opt-in completeness check for CI. It fails when a specification in the manifest lacks an overlay for one of the listed locales.

Categories and inherited specifications

Overlays attach to a specification, not to a product name.

• Overlays for a category belong on the category specification and apply to every product that inherits it.
• Overlays declared on a product with inheritSpec: true are ignored; the product uses the category's overlays.
• If storing the overlays fails after a new category specification has been created, the new specification is deleted again, in the portal and in the CLI. Products that inherit it can lose their link; re-run upload-spec to restore them.

Related topics

• Translated specifications
• Translating a specification
• Reference: API catalog
• apidex-cli on GitHub, the manifest keys and flags