Translation contract 1.3.0-beta.1

Status: experimental prerelease. Applies to the exact 1.3.0-beta.1 input version. Stable 1.2.0 remains available on the stable release and main. Unsupported spec versions must be reported; a translator must not silently interpret beta input as 1.2.0.

Purpose

This document defines the minimum contract for translating CMMF models into a target CMS schema.

It does not define translator implementation details. It defines what a translator must accept, produce, and explain.

Input

The translator must accept:

• one CMMF manifest
• one or more CMMF model files
• an explicit target platform identifier
• an optional translation mode
• optional translator configuration

For CMMF 1.3.0-beta.1, translators should treat field-level list as the canonical repeatability signal. Translators may also accept legacy relation.cardinality on reference fields for compatibility.

Output

The translator must produce:

• target platform schema artefacts
• a decisions log
• validation errors and warnings, if any

Decisions Log

The decisions log should record non-trivial translation choices, including:

• how contained ownership was represented
• how object structures were mapped
• how unsupported validations were handled
• the disposition of every model-level validationHints declaration
• how unsupported richTextConfig capabilities were handled
• whether legacy relation.cardinality input was normalised to list
• any inferred defaults or fallbacks
• any platform limitations or lossy mappings

Translation Modes

Suggested modes for future translators:

• strict: preserve intent as literally as possible
• optimised: adapt output for target-platform best fit

Allowed Variation

The following may vary by translator and target platform:

• whether contained relationships become embedded objects or separate types
• how editorial metadata is represented
• how richTextConfig capabilities map onto target editor features
• how governance metadata is preserved or omitted
• how non-authoritative translation hints influence output

Non-Negotiable Behaviour

A translator must not:

• mutate the meaning of the source model silently
• ignore required constraints without reporting them
• silently widen richTextConfig allowlists when the target editor cannot enforce them
• drop relationship semantics without a logged decision
• silently accept conflicting list and legacy relation.cardinality values on the same field
• silently drop a document-level validation hint, including prose or an unknown dialect
• treat a hint as permission to weaken authoritative field requirements

Document-Level Hint Dispositions

Each hint must receive a record containing the source model ID, hint ID, a disposition, and a non-empty reason. This is a required information contract; the log’s file format, filename, and property names are translator-defined.

Disposition	Meaning
mapped	The declared intent and severity are preserved by the generated target checks, whether native or explicitly generated custom validation.
degraded	Part of the intent survives, but checks or severity are weakened; explain exactly what was lost.
unmapped	No usable target representation was produced; explain why.

Preserving description text as editorial guidance without preserving the declared checks is degraded. An unknown expression dialect may be degraded if meaningful editorial guidance is generated, or unmapped otherwise. No dialect is implicitly supported. Prose-only hints must also be accounted for; guidance alone is recorded as degraded so it cannot be mistaken for generated validation.

Illustrative YAML (not a prescribed serialization):

decisionsLog:
  - modelId: article
    hintId: external-requires-source
    disposition: degraded
    reason: >-
      This Contentful-targeting translator generated editorial help text only.
      It did not generate a custom app or other validation integration, so
      conditional non-empty source_url is not enforced.
  - modelId: article
    hintId: author-or-source
    disposition: mapped
    reason: >-
      Generated custom document validation checks non-empty author or source_url
      using the CMMF empty-value definition and reports the declared severity.

These are examples of translator output, not claims that CMMF provides a Contentful integration or guarantees native support. If one hint cannot be fully represented, the translator must report it even in an optimised translation. Whether translation aborts is a documented translator policy; hint severity alone does not require translation to abort.

Source: CMMF 1.3.0-beta.1 at a0c7a3d8 · Download original Markdown