← Back to catalogue
Published

API / Interface Contract

vr.wm-sft-003 · wm-sft-003-api-interface-contract

Describe a versioned logical interface with immutable revisions, consumer pins, compatibility evidence and endpoint bindings.

World Models Information and virtual systems INF.SFT.API

Bundle → Layer → Finding → Questions Filled

3 bundles · 4 layers · 5 findings · 10 questions

Contract and revisions The logical interface and its immutable versions.

Revision record

A published revision of the contract.

Immutable revision

A revision with its version, content hash and publication date.

  1. Which version and content hash identify this revision?
  2. Has the published revision content changed since publication?

Interface content

The operations, messages, schemas and errors in the revision.

  1. Which operations or message channels does the revision define?
  2. Which data schemas and error codes does it use?
Compatibility and consumers Who depends on which revision and whether changes break them.

Consumer pins

Which consumers rely on which revision.

Pinned dependency

A consumer and the revision it is pinned to.

  1. Which consumers are pinned to this revision?
  2. Will a consumer be affected when this revision is deprecated?

Compatibility evidence

Proof that a new revision is compatible or breaking.

Compatibility check

The result of a compatibility check between two revisions.

  1. Is the new revision backward compatible with the previous one, and by which check?
  2. Do contract tests from consumers pass against the new revision?
Bindings and lifecycle Where the contract is served and how it ends.

Endpoint bindings and deprecation

Endpoints implementing a revision and its lifecycle status.

Binding and status

The endpoints bound to a revision and its deprecation or sunset dates.

  1. Which endpoints implement this revision, and in which environments?
  2. Is the revision active, deprecated or sunset, and from what date?

Classifiers Filled

Family
World Models
Category
Information and virtual systems
Entry kind
entity
Navigation path
NAV.INF.SFT.API
Domain
INF.SFT.API
Industry
Cross-industry
Tags
apiinterfacecontractinf.sft.api

What it is Filled

An API or interface contract is the versioned, machine-readable description of a logical interface between software components: its operations or messages, data shapes, errors and guarantees. Each revision is immutable once published; consumers pin the revision they depend on, compatibility between revisions is shown by evidence, and the contract is bound to one or more network endpoints that implement it. The running endpoint and the implementing code are separate records.

In scope

  • Logical contract identity, accountable roles, revision manifests and description profiles
  • Declared operations, message patterns, payload references, failures, effects and access requirements
  • Consumer pins, directional compatibility evidence, endpoint bindings, drift reports and retirement records

Out of scope

  • Payload schema and data-contract master semantics or their evaluation engines
  • Endpoint connectivity, exposure, deployment, routing execution and shutdown
  • Message instance custody, delivery and retention; event occurrence identity and lifecycle
  • Implementing code, credentials, production test execution and universal protocol conformance

Why it exists Filled

Describe a versioned logical interface with immutable revisions, consumer pins, compatibility evidence and endpoint bindings.

Distinguishing features Filled

  • It describes the logical interface, while an endpoint is a network location that serves it.
  • Published revisions are immutable; change means a new revision, not an edit.
  • Consumer pins and compatibility evidence make the dependency graph explicit.
  • Distinct from a data schema or data contract, which governs a dataset rather than callable operations.

What robots and AI may and may not do Filled

Must not

  • Edit a published revision in place.
  • Publish a breaking change under a version that signals compatibility.
  • Sunset a revision while consumers remain pinned without notice.
  • Include credentials, keys or personal data in contract examples.
  • Call production endpoints with side effects to test a contract.

Only with a human decision

  • Approving a breaking change or a new major version.
  • Setting deprecation and sunset dates for a revision.

May

  • Publish new revisions and generate documentation and client code from them.
  • Run compatibility checks between revisions and report breaking changes.
  • List consumers pinned to a revision before deprecation.
  • Validate that an endpoint conforms to its bound revision.

Moral aspects Filled

  • Undeclared breaking changes can halt services that people depend on.
  • Interfaces that expose personal data need purpose limits stated in the contract.

Who is affected

  • Consumer developers and their users
  • API owners and operators
  • People whose data passes through the interface

Owners Filled

Steward

The team that owns the implementing service answers for the contract, its revisions and its deprecation policy.

Roles

Contract owner
Accountable for scope, promises and approved lifecycle policy.
Contract steward
Maintains identity, drafts, pins and evidence provenance.
Compatibility reviewer
Assesses directional evidence and unresolved counterexamples.
Security reviewer
Reviews access declarations, examples and restricted projections.
Consumer representative
Attests dependencies and migration readiness without claiming complete consumer discovery.

Master systems

  • API registry or catalogue
  • Source repository holding contract files
  • API gateway configuration

Links to other meta-models Filled

references

  • WM-DAT-004 - Payload meaning, constraints and data obligations remain externally mastered. This contract pins revisions and binds interface positions only. Registry relationships remain candidates requiring pinned adoption bindings.
  • WM-SFT-018 - Network identity, connectivity and exposure lifecycle remain endpoint-owned. Only revision-specific bindings and assertion evidence are local. Registry relationships remain candidates requiring pinned adoption bindings.
  • WM-REC-003 - Addressed message identity, payload custody, delivery and retention remain message-owned; only exchange description and occurrence references belong here. Registry relationships remain candidates requiring pinned adoption bindings.
  • WM-ACT-015 - Non-addressed occurrence identity, time and observation lifecycle remain event-owned. A contract describes permitted exchanges and can be cited by events. Registry relationships remain candidates requiring pinned adoption bindings.
  • WM-SFT-001 - The implementing product, builds and release operations are external references; contract ownership does not follow automatically from an endpoint operator. Registry relationships remain candidates requiring pinned adoption bindings.

aligned

  • OpenAPI 3.1.1 - Selected HTTP description projection; mapping and round-trip evidence required.
  • AsyncAPI 3.0.0 - Selected asynchronous description projection with explicit application perspective.
  • JSON Schema Draft 2020-12 - Payload dependency alignment; dialect and resource identity do not prove validity.
  • Semantic Versioning 2.0.0 - Optional version policy; not a universal mandate or compatibility proof.

neighbor

  • WM-DAT-004 Data Schema / Data Contract - Payload meaning, constraints and data obligations remain externally mastered. This contract pins revisions and binds interface positions only.
  • WM-SFT-018 Network / Endpoint - Network identity, connectivity and exposure lifecycle remain endpoint-owned. Only revision-specific bindings and assertion evidence are local.
  • WM-REC-003 Message - Addressed message identity, payload custody, delivery and retention remain message-owned; only exchange description and occurrence references belong here.
  • WM-ACT-015 Event - Non-addressed occurrence identity, time and observation lifecycle remain event-owned. A contract describes permitted exchanges and can be cited by events.
  • WM-SFT-001 Software Product - The implementing product, builds and release operations are external references; contract ownership does not follow automatically from an endpoint operator.
  • WM-DAT-008 Data Product - Incoming access-route references may pin this contract. They do not transfer product identity or lifecycle into the interface.
  • wm-dat-004-data-schema-data-contract - Data contracts govern datasets, while API contracts govern operations.

part-of

  • wm-sft-001-software-product - Interfaces are offered by software products and services.

related

  • wm-sft-018-network-endpoint - Revisions are bound to the endpoints that serve them.

What else AI and robots need to interact with it Filled

Identity and identifiers required Filled

  • A contract is identified by a name or URI in an API registry, and each revision by a version number and content hash.
  • Semantic versioning is commonly used to signal compatibility between revisions.

Direct properties not applicable Not applicable

Not applicable

An interface contract is a software artifact with no physical properties to measure.

Recognition required Filled

  • A contract is recognized as a description document such as an OpenAPI, AsyncAPI, protocol buffer or WSDL file with a version.
  • Often confused with the implementation, with a running endpoint or with informal documentation pages.

Capabilities and actions required Filled

  • Revisions can be published, compared, tested, deprecated and sunset.
  • Clients, servers, mocks and documentation can be generated from a revision.

Hazards and failure modes required Filled

  • Outages from unannounced breaking changes.
  • Security exposure when undocumented operations are served.
  • Drift between the contract and what the endpoint actually does.

Standards and interfaces required Filled

  • OpenAPI Specification for HTTP APIs.
  • AsyncAPI Specification for message-driven interfaces.
  • Protocol Buffers and gRPC service definitions.
  • HTTP semantics in RFC 9110.

Context of use required Filled

  • Used wherever software components, services or organizations integrate through APIs.
  • Public sector and regulated APIs may be subject to published API guidelines or interoperability rules.

Sources Filled

  1. OpenAPI Specification v3.1.1 - OpenAPI Initiative
  2. AsyncAPI Specification 3.0.0 - AsyncAPI Initiative
  3. RFC 9110: HTTP Semantics - Internet Engineering Task Force
  4. JSON Schema Core - JSON Schema project
  5. Semantic Versioning 2.0.0 - Semantic Versioning project
  6. RFC 9457: Problem Details for HTTP APIs - Internet Engineering Task Force
  7. RFC 9745: The Deprecation HTTP Response Header Field - Internet Engineering Task Force
  8. RFC 8594: The Sunset HTTP Header Field - Internet Engineering Task Force
  9. OpenAPI Specification (OpenAPI Initiative)
  10. Semantic Versioning 2.0.0
  11. RFC 9110 HTTP Semantics (IETF)

Open questions

  • Run coordinator source HTTP checks, review current source versions and errata, and complete claim-level verification without treating successful retrieval as substantive proof.
  • Develop and test adoption schemas and mappings with mutable reference targets, partial failures, directional incompatibility, unknown consumers, access changes and withdrawal exceptions.
  • Research protocol-specific RPC, streaming, pagination, rate control and binary/ABI profiles within the contract boundary.
  • Restore independent external review before any promotion toward canonical or publishable-draft assurance.
  • Independent external provider review is absent; the separate local audit is a self-audit.
  • Direct HTTP checks were not attempted under the owner-reported sandbox block. Browser-selected sections were read; current versions, errata and full claim support remain a verification hold.
  • Nested instance schemas, immutable dependency packaging, reference resolver implementation and acceptance fixtures remain unimplemented.
  • Protocol-specific RPC, streaming, callback security, pagination, rate control and binary/ABI compatibility profiles need separate qualified work.
  • Formal semantic compatibility, comprehensive consumer discovery and runtime enforcement cannot be inferred from these records.

Machine files

Provenance

world-models research · reviewable-draft

Built from: models/wm-sft-003-api-interface-contract/spec.yaml, ver-cy/world-models/card-supplements/wm-sft-003-api-interface-contract.json