Make systems agree on meaning, behavior, and change—not just message format.

1. Define the interoperability contract

For every important exchange, document:

• provider and consumer owners;
• business purpose and authoritative source;
• transport/protocol;
• request/event/file schema;
• identifiers and reference data;
• units, timezone, precision, encoding, and null semantics;
• authorization and data classification;
• error model and retry behavior;
• availability/freshness/latency expectations;
• versioning and deprecation policy;
• change notification path;
• test/conformance evidence.

The contract should be version controlled and discoverable from the service/data catalog. Avoid undocumented conventions that exist only in one developer's code.

2. Control semantics before mapping fields

Field-name mapping does not solve semantic disagreement. Define critical terms such as customer, case, encounter, active, closed, balance, effective date, event time, and status using domain-owned definitions.

For important fields, record

• definition and owner;
• data type and allowed values;
• unit/scale/precision;
• timezone/calendar behavior;
• whether absence, null, zero, and unknown are distinct;
• source of reference values;
• effective dates/versioning for code sets;
• known mappings and lossy transformations.

When two domains legitimately use different meanings, preserve the context and map explicitly rather than forcing one ambiguous enterprise term.

3. Treat identifiers as architecture

Interoperability often fails because systems cannot reliably identify the same entity or event. For each identifier, define namespace, issuing authority, uniqueness, stability, lifecycle, merge/split behavior, and whether identifiers can be reused.

• Do not assume database primary keys are portable enterprise identifiers.
• Preserve source identifiers when mapping into another domain.
• Record crosswalk confidence and provenance for matched entities.
• Design for corrected or merged identities without rewriting history silently.
• Use idempotency identifiers where repeated requests/events could create duplicate effects.

4. Use API specifications as executable contracts

OpenAPI 3.2.0 can describe HTTP API operations, parameters, payloads, responses, security schemes, and related interface behavior.^{OpenAPI 3.2.0} Use the description to generate documentation and tests where helpful, but treat the normative specification and runtime behavior as the real compatibility target.

JSON Schema 2020-12 can define machine-readable constraints for JSON payloads.^{JSON Schema specification} Test both valid and invalid examples. A schema that no production consumer validates is documentation, not enforcement.

Contract tests should cover

• required/optional fields;
• unknown fields and forward compatibility;
• boundary values and precision;
• enum/reference changes;
• content/media types;
• authentication/authorization outcomes;
• pagination/filter/sort behavior;
• idempotency and retries;
• error responses;
• deprecation/version behavior.

5. Use HTTP semantics consistently when HTTP is the transport

RFC 9110 defines the semantics of HTTP methods, status codes, representation metadata, content negotiation, and related behavior.^{RFC 9110 — HTTP Semantics}

• Use methods consistently with their defined safety/idempotency semantics.
• Return status codes that reflect the protocol-level outcome.
• Do not encode every error as HTTP 200 with an application error string.
• Use cache semantics deliberately rather than accidentally.
• Document conditional requests/concurrency behavior where updates can conflict.

RFC 9457 defines JSON/XML problem details so APIs can return machine-readable error types and contextual details without inventing a completely different envelope for each service.^{RFC 9457 — Problem Details for HTTP APIs}

6. Govern events and files with the same rigor as APIs

Batch files, queues, and event streams need versioned contracts too.

• schema/event type and version;
• producer and consumer ownership;
• delivery semantics and ordering guarantees;
• event time versus processing time;
• deduplication key;
• replay policy;
• retention window;
• poison/dead-letter handling;
• breaking-change process.

For files, define filename/partition conventions, encoding, delimiter/escaping, compression, checksum, manifest/control totals, transfer completion semantics, and reprocessing behavior.

7. Make compatibility policy explicit

Version numbers alone do not tell consumers whether a change is safe. Publish compatibility rules such as:

• adding optional fields is backward compatible if consumers ignore unknown fields;
• removing or renaming fields is breaking;
• changing meaning without changing field name is breaking even if syntax is unchanged;
• tightening validation can break existing producers;
• enum additions can break consumers that assume exhaustive values;
• reference-data/code-set changes need effective dates and consumer coordination.

Define deprecation notice, support overlap, migration evidence, and retirement criteria. Keep old interfaces only as long as justified; indefinite compatibility can become a security and maintenance risk.

8. Make data services and datasets discoverable

DCAT 3 is a W3C Recommendation for describing catalogs, datasets, data services, distributions, dataset series, and version relationships in an interoperable way.^{W3C DCAT 3} Use it where web/federated catalog interoperability is valuable.

At minimum, a catalog should let consumers find owner, purpose, interface/schema, classification/restrictions, quality/freshness, version, support/contact, and deprecation status. Catalog entries should be maintained from source-of-truth metadata where possible rather than becoming another stale documentation repository.

9. Test portability as an exit scenario

Do not equate a vendor's export button with portability. For important platforms or data services, test:

• whether all required data can be exported;
• format/schema/documentation completeness;
• preservation of identifiers and relationships;
• metadata/configuration needed to interpret the export;
• volume/time/cost of export;
• re-import into a replacement or independent validation environment;
• credential/key/secret separation;
• post-exit deletion or residual-access requirements.

If an EU Data Act role or other legal portability obligation is actually in scope, attach it through the applicability register rather than presenting it as a universal API-design mandate.^{EU Data Act}

10. Build conformance evidence into delivery

Interoperability should be tested from both provider and consumer perspectives.

• schema/spec lint and validation;
• producer contract tests;
• consumer compatibility tests;
• reference example payloads;
• negative/error tests;
• round-trip or reconciliation tests where data is transformed;
• version compatibility matrix;
• performance/volume tests where timing is part of the contract;
• security/access tests;
• migration/exit tests for high-consequence services.

Retain enough evidence to answer which contract/version was tested, which implementation passed, and which exceptions were accepted.

Measure interoperability as operational performance

• important interfaces with version-controlled contracts and named owners;
• consumers covered by automated compatibility tests;
• breaking changes detected before production;
• semantic/reference-data defects causing reconciliation failures;
• deprecated interfaces past retirement date;
• integration incidents caused by undocumented behavior;
• time required to identify impacted consumers after a contract change;
• high-consequence services with tested export/migration paths.

30-day interoperability reset

1. Week 1: identify the ten highest-consequence interfaces and assign provider/consumer owners.
2. Week 2: document schemas, semantics, identifiers, error behavior, and version policy.
3. Week 3: add contract/compatibility tests and run one breaking-change simulation.
4. Week 4: clean deprecations, catalog the interfaces, and test one export/recovery path.

Current sources

• OpenAPI Specification 3.2.0
• JSON Schema 2020-12
• RFC 9110 — HTTP Semantics
• RFC 9457 — Problem Details for HTTP APIs
• W3C Recommendation — DCAT Version 3
• EU Data Act (apply only where scoped role/obligation is relevant)