Define the operation
Check the Registry and existing standards first. A new type needs a distinct meaning that more than one service can implement. Name the effect precisely: approving a review is different from authorizing a send.
Start with an existing JSON contract. Describe the required details, each choice’s meaning, effects, inputs and outcomes. Say which authority modes it permits. When a decision arrives, the service must reject it if any material term has changed. Keep endpoint paths and native request formats in the service binding.
Submit for review
The browser checker validates and previews the contract locally. Continue in GitHub to propose the JSON file under specifications/map-0.3/contracts/. Include these companion changes in the same pull request:
- A complete description in
examples/source.json, keyed by the type slug. Generation supplies the profile, context and contract digest. - A record in
registry.jsonnaming its category, maintainers, current version and status. Names, summaries and operations come directly from the contract. - Relevant standards, motivation and implementation details in the pull-request description. Identify what an existing definition cannot express.
The suggested filename is for the site. Choose a distinct page slug if another contract already uses it; the identifier inside the contract stays the protocol identity.
Generate and check the projections before review. On merge, the contract appears in the Registry, search, downloads and the reader’s type chapter. Adding a type does not require releasing every language package.
Check a change locally
npm ci
npm run spec:generate
npm run verifyThe browser and repository use the same contract and service-record parsers. Repository verification also checks examples, digests and generated artifacts. Review still decides whether a definition is clear, safe and distinct from existing standards.
Connect an existing service
A service can implement an existing type without creating a new one. Select Service support in the checker, choose the exact contract and prepare a record underspecifications/map-0.3/implementations/. Name the service, maintainer, binding, supported operations and source of the support claim. A built-in service does not need a downloadable connector. If you offer an installable integration, include its format and verified artifact digest. Reuse the service's existing authorization. Thebinding guide explains the required association; the interface research covers existing standards and their gaps.
Follow the implementation record requirements. A declaration states support claimed by the maintainer. A report records observed behavior and how another person can repeat the checks. Registry listing does not connect an account or certify the service.
Show what works
For a report, give the exact contract ID, version and digest; implementation revision; tested roles and operations; setup; and reproduction instructions. Record actual observations for the conformance scenarios, including failed checks and missing coverage.
Demonstrate the service read and decision: a changed revision, a revoked permission and a competing decision must not produce an unauthorized effect. State who operates the implementation. A declaration of support is not an interoperability result.
Improve the specification
Point to the requirement and the concrete case it fails to handle. Include the observed or expected behaviour, and propose the smallest correction that resolves it.