Contract: 1.0.0-draft Contract compatibility Maturity: Draft OpenAPI AsyncAPI
Versioned, implementation-independent contracts for CoreLink APIs and events. This repository is the normative machine-readable handoff boundary between the Platform runtime and Console, SDKs, CLI, mock server, MCP server and external integrations.
| Path | Intended contract |
|---|---|
openapi/corelink-public-v1.yaml |
Partner/product-facing public API |
openapi/corelink-admin-v1.yaml |
Privileged administrative API |
openapi/corelink-internal-v1.yaml |
Internal service contract; never expose as public API |
asyncapi/corelink-events-v1.yaml |
Event channels/payloads |
schemas/ |
Reusable JSON Schemas for device, command, event envelope and errors |
postman/ |
Versioned collection/environment/examples |
docs/compatibility-policy.md |
Compatibility/versioning rules |
docs/compatibility-matrix.md |
Consumer/release compatibility inventory |
docs/runtime-parity.md |
Runtime parity boundary/evidence expectations |
docs/terminology.md |
Shared public-contract vocabulary |
The immutable v1.0.0-draft baseline defines the reviewed public Device + Command slice and canonical event envelope. It is intentionally narrower than the private runtime and Console product surface.
Broader Asset/binding/telemetry/location/alerts, partner credential/webhook/usage/operations and full event schema work remains owned by the corresponding API-02/API-03/API-04 backlog and runtime acceptance gates.
A contract tag is reproducibility evidence; it is not by itself a runtime/SDK/Stable-support claim.
See CHANGELOG.md, compatibility policy, compatibility matrix and runtime parity.
- Public device identity is
corelink_device_id; provider/integration IDs remain implementation details. - Model CoreLink resources, not raw provider payloads.
- Keep public, admin and internal audiences in separate documents.
- Define authentication, tenant scope, authorization failures, pagination, idempotency and problem responses for every operation.
- Preserve provider-neutral semantics for Console/SDK/CLI/MCP consumers.
- Breaking changes require an explicit versioned contract and coordinated migration/release decision.
- Platform implements/accepts runtime behavior; merged code alone is not parity evidence.
- Console may isolate missing read models in an adapter, but fallbacks are not normative API contracts.
- TypeScript/Python SDKs are generated prerelease consumers and must retain immutable contract provenance before supported publication.
- Java/CLI/mock/MCP remain Scaffold/Planned until their own implementation/release gates pass.
- developer-docs explains use of this contract without copying/forking normative schemas.
- Confirm product/runtime ownership and the primary Product Epic/implementation issue.
- Validate OpenAPI/AsyncAPI syntax and references.
- Add representative request, response, authorization and error examples.
- Assess backward compatibility and migration impact.
- Reconcile affected Platform, Console, SDK, mock/MCP/CLI, developer-docs and website claims.
- Run the contract compatibility/parity checks required by the current maturity gate.
Use CoreLinkPlatform/developer-docs for tutorials, concepts, operational guidance and runnable developer journeys. This repository remains the schema/compatibility source of truth.