The specification

This is the machine-checkable half of the import protocol: the artifact formats, published as JSON Schema (draft 2020-12) plus prose, at stable URLs, under a license that lets anyone implement them. No login, no NDA.

Two properties worth knowing before you read further:

• The schemas are generated, never hand-written. Every JSON Schema below is produced mechanically from the same typed sources the engine itself runs. The published spec cannot say more — or other — than the code does.
• The spec covers the contract, not the mechanism. What an artifact is, how it is shaped, and how to verify it is all here. How the engine decides what goes into one — matching, confidence, normalization — is not part of the protocol and is not published.

The artifacts

Artifact	Prose	Schema
Signed Import Receipt v1	Specification	import-receipt.v1.schema.json
Portable Import Contract v1	Specification	import-contract.v1.schema.json
Benchmark Scorecard v1	Specification	benchmark-scorecard.v1.schema.json
Error registry + envelope	Specification	error-registry.v1.json

The REST surface the artifacts travel over is documented by the OpenAPI 3.1 document: import-suite-v1.openapi.yaml — the same drift-gated file the service is tested against, published verbatim.

Versioning

Each artifact embeds its own version number (receiptVersion, contractVersion, scorecardVersion), so a stored artifact stays checkable regardless of what the engine ships later. Revisions are dated, and the change rules are written down and enforced: adding an error code or an optional field is a feature; renaming or removing one is a breaking change. The full policy, including deprecation windows: Versioning & breaking changes.

Some schemas reserve field names for capabilities that are still being built (they are marked optional). A reserved name is a promise about shape, not a claim the capability exists — the prose page for each artifact says what is live.

Revisions. 2026-08-09: the signature algorithm was unified to ES256 across the product (details), before any production artifact existed; pre-revision EdDSA envelopes verify with the spec repository’s tagged v0.1.x verifier. 2026-08-08: initial publication.

License

CC BY 4.0

The specification — these pages, the JSON Schemas, the error registry, and the published OpenAPI document — is licensed under Creative Commons Attribution 4.0 (notice). You may copy, redistribute, and implement it, commercially or not, with attribution to “Mildport protocol specification”. The license covers the specification only: Mildport software, packages, and images are licensed separately, and no rights to the Mildport name or marks are granted.

The schemas are also mirrored in a public repository — github.com/Mildport/mildport-spec — together with an MIT-licensed, zero-dependency receipt verifier; every spec revision lands there as a dated, tagged commit you can pin an implementation against.

One more thing the license makes possible: a second implementation. There is exactly one today — we say so plainly, and that page lists everything a second one would need.