How ODP evolves
Match the review to the change
A corrected link does not need the same evidence as a new field that changes what Agents and Services exchange. Classifying the change establishes which artifacts, compatibility questions, and implementation evidence reviewers must examine.
| Change | Examples | Review |
|---|---|---|
| Editorial | Typographical corrections, clearer wording, and repaired links. | Normal review with no change to request or response behavior. |
| Support artifact | Schemas, examples, guides, vectors, and harness checks. | Verify alignment with the draft and run the repository checks. |
| Clarification | Language that resolves an ambiguous requirement without changing its intended behavior. | Review compatibility and every artifact that encodes the clarified rule. |
| Protocol behavior | JSON fields, link relations, errors, algorithms, security rules, and conformance requirements. | Require design review, compatibility analysis, implementation evidence, and test vectors. |
Propose one concrete change
Open a GitHub issue or discussion before changing public JSON fields, request or response behavior, or conformance rules. Describe the problem through the Agent and Service interaction that exposes it, rather than beginning with a preferred field or implementation.
- Describe the interaction: identify the Agent, Service, request, response, and observable problem
- Analyze the consequences: cover compatibility, migration, versioning, security, privacy, and affected implementations
- Submit a focused change: update the normative prose and every schema, example, vector, registry, or guide that represents the same behavior
- Provide executable evidence: demonstrate the behavior in implementations and conformance tests before treating it as stable
Evaluate compatibility from observable behavior
Repository history does not determine whether a change is compatible. Review what existing Agents send, what existing Services return, and whether either side must change to preserve correct behavior.
| Change | Effect on odp_version |
|---|---|
| Editorial or non-normative correction | No protocol-version change. |
| Compatible optional behavior | Increment the minor version when the behavior becomes normative. |
| Removal or incompatible redefinition | Increment the major version and publish new versioned resources. |
An Internet-Draft suffix such as -01 identifies an IETF publication. It does not change odp_version or establish compatibility by itself.
A revision within the same major version can deprecate a field, value, operation, or behavior without removing it from that major-version family. The draft records the deprecation and its migration guidance. Removing or incompatibly reusing the deprecated behavior requires a new major version.
Read the versioning rulesRequire evidence before declaring behavior stable
A normative behavior needs executable evidence in the Node.js reference implementation and conformance evidence from an independent implementation. This checks both that the rule can be implemented and that separate implementations interpret it consistently.
The pull request also updates every affected schema, example, test vector, conformance rule, registry, and guide. Security-sensitive changes receive an explicit threat and privacy review instead of relying only on successful examples.
Existing test vectors change only to correct an error or to represent an approved compatibility decision. A proposed behavior does not rewrite existing evidence merely to make an implementation pass.
Validation and conformancePublish snapshots and revisions for different purposes
Repository deployments, Git tags, Internet-Draft revisions, implementation releases, and odp_version identify different things. A publication process must not treat them as interchangeable version numbers.
In the specification repository, ietf/ contains the source documents and support material, while docs/ contains the published website. Repository checks reproduce the rendered files and reject generated output that has drifted from its source.
Use latest for convenience
Each successful deployment replaces the latest GitHub release with rendered artifacts from the deployed main commit. The snapshot is useful for current work, but it is not immutable.
Keep published revisions immutable
A submitted Internet-Draft receives a tag and release matching its full document name. A correction is published as the next draft revision instead of moving that tag.
Stable URLs for schemas and other published resources remain available for the major-version family they identify. An incompatible resource receives a new versioned URL rather than changing the meaning of an existing stable URL.
Use the right channel
Public technical proposals belong in the ODP specification repository. Vulnerabilities and security-sensitive specification defects use the private reporting channel so maintainers can coordinate a fix before publishing exploitable details.
- Governance policy: read the complete authority, compatibility, evidence, and publication policy
- Contribution guide: follow the branch, pull-request, repository-check, and draft-publication workflow
- Specification questions: contact the maintainers about standards or specification interpretation
- Security reports: report vulnerabilities privately instead of opening a public issue
Next steps
Read the specification
Use the normative draft when implementing or reviewing ODP behavior.
ODP specificationPropose a change
Bring a concrete Agent and Service interoperability problem to the public repository.
Open GitHub
On this page