--- mpf: '0.7' title: Versioning and deprecation — ESFI Docs url: https://docs.esfi.eu/standards/mpf/versioning/ mpf-url: https://docs.esfi.eu/standards/mpf/versioning/index.mpf organization: European Strategy & Future Infrastructure domain: docs.esfi.eu lang: en updated: '2026-11-03' author: ESFI provenance: human source-hash: 70af77f8df1ab46e30cc72eb28ee64dcf199187647ad644a4afa0573a49c4f9f toc: - level: 1 text: Versioning and deprecation id: versioning-and-deprecation - level: 2 text: Version numbers id: version-numbers - level: 2 text: Specification, implementation and practice id: specification-implementation-and-practice - level: 2 text: Published versions are permanent id: published-versions-are-permanent - level: 2 text: Deprecation and retirement id: deprecation-and-retirement - level: 2 text: Current and previous MPF versions id: current-and-previous-mpf-versions - level: 2 text: Positions are versioned differently id: positions-are-versioned-differently - level: 2 text: On this page id: on-this-page spec-origin: esfi.eu content-origin: docs.esfi.eu content-id: esfi:page:standards-mpf-versioning content-parity: html: true human-visible-source: true hidden-sections: false summary: A version names a contract that exists, not one that is planned. index: true confidence: confirmed content-type: reference companion-footer: ESFI — civilization infrastructure · https://esfi.eu companion-contact: mailto:hermes@esfi.eu preferred-representation: mpf companion-scope: cite: true summarize: true train: true index: true relay: false language-variants: en: https://docs.esfi.eu/standards/mpf/versioning/index.mpf fr: https://docs.esfi.eu/fr/standards/mpf/versioning/index.mpf nl: https://docs.esfi.eu/nl/standards/mpf/versioning/index.mpf de: https://docs.esfi.eu/de/standards/mpf/versioning/index.mpf hr: https://docs.esfi.eu/hr/standards/mpf/versioning/index.mpf mpf-id: 4dcf62eec3c28dd7172bb49789276561fc8610101458d451e462f47895acdf5b --- Language ✕ /standards/mpf/versioning/index.mpf[open file ↗](/standards/mpf/versioning/index.mpf)[spec ↗](/standards/mpf/0.7)✕ loading… # Versioning and deprecation {#versioning-and-deprecation} **A version names a contract that exists, not one that is planned.** ESFI format versions identify an implemented contract. A version describes what a conforming implementation actually emits or accepts; it is not a roadmap label. ## Version numbers {#version-numbers} Published specifications use a **minor version** such as `0.7`. The document and generated output declare that minor version. A new minor version is required when the format contract changes: fields are added or removed, required behaviour changes, serialisation or identity rules change, or an existing consumer can no longer rely on the previous specification. A breaking change is any change that can make previously conforming producers or consumers incompatible, including changing the meaning of an existing field or making an optional field required. **Patch fixes do not change the version declared by a document.** Corrections that leave the format contract unchanged are recorded as changelog entries against the published minor version. Examples include correcting prose, clarifying an already-implemented rule, or fixing an implementation defect so that output again matches the published contract. If a change alters the contract rather than restoring or clarifying it, it is not a patch fix; it requires a new minor version. ## Specification, implementation and practice {#specification-implementation-and-practice} The MPF documentation marks every rule with one of three statuses: **Specification 0.7**, **Reference implementation** or **ESFI practice**. See the [Overview](/standards/mpf). The markers also describe how a rule can change status: - A **reference implementation** behaviour that the specification text does not describe becomes normative only when a published specification version describes it. Until then, implementers may rely on it in practice but not as part of the contract. - An **ESFI practice**, such as a discovery convention used on ESFI sites, becomes part of the contract only through a new specification version. Documenting it does not make it normative. - A rule is never promoted to the specification by a patch fix. Promotion changes the contract, and a changed contract requires a new minor version. This keeps the published specification narrow and reliable: it states what conforming producers and consumers can depend on, and nothing that is merely convenient or customary. ## Published versions are permanent {#published-versions-are-permanent} Once an ESFI format version is published, its specification page remains published and reachable. A newer version does not replace the historical page in place. This gives implementers a stable reference for documents that continue to declare an older version, and makes historical machine-readable output interpretable without reconstructing an earlier specification. ## Deprecation and retirement {#deprecation-and-retirement} A version may be **deprecated** when ESFI recommends migration to a newer version. Deprecation changes the recommendation, not the historical specification: the deprecated version remains reachable and its documented contract is not rewritten to match the successor. A version is **retired** when ESFI no longer treats it as a current implementation target. Retirement is recorded on that version’s page together with the successor, when one exists. Retirement does not remove the page. Consumers should read the version declared by the document they are processing. Producers should emit the version whose published contract they implement. ## Current and previous MPF versions {#current-and-previous-mpf-versions} MPF documents currently declare `mpf: '0.7'`. The implemented behaviour is documented in the [Specification 0.7](/standards/mpf/0.7). MPF 0.6 is the previous published version. Its [Specification 0.6](/standards/mpf/0.6) remains available for documents that still declare `mpf: '0.6'`. ## Positions are versioned differently {#positions-are-versioned-differently} The topic pages on this site are positions, not format contracts. They do not carry version numbers. When a position changes materially, the change is recorded at the foot of the topic page with its date. See [How to read our claims](/our-approach/how-to-read-our-claims). * * * **Related:** [Overview](/standards/mpf) · [Implementation registry](/standards/mpf/implementation-registry) · [Publishing and discovery](/standards/mpf/publishing-and-discovery) ## On this page {#on-this-page} ESFI — civilization infrastructure · https://esfi.eu