This chapter explains that the version object of OpenAgenet (OAN) is not a single number, but a set of coordinates across multiple layers:

Release records must associate the layers above and must not use Cargo or npm version numbers as substitutes for protocol, schema, or deployment versions. One implementation version may support multiple protocol or schema versions, and one resource DID may correspond to multiple historical DID Documents and ResourcePackage versions; therefore, releases, compatibility, migration, and rollback must all record the actual mappings. Version records must also distinguish “code committed,” “artifact built,” “service deployed,” and “change effective,” so that repository state is not mistaken for production state.

The relationships among version layers can be checked as follows:

24.1 Specification Version Management

The unified technical specification uses major, minor, and patch versions to record structural, semantic, and errata changes. A major version change means that existing implementations may no longer interoperate directly; a minor version is used for backward-compatible extensions; and a patch version is used for clarifications or corrections that do not change specification semantics. Each release retains the affected sections, release date, status, and implementation mapping.

24.2 Protocol Version Management

Node protocols and public APIs should explicitly define version identifiers, supported ranges, request/response schemas, error semantics, and negotiation methods. During the transition period, old clients may use only profiles that the server still declares as supported. The server must not silently change signatures, versions, publication sequences, or governance decisions merely to accommodate legacy requests; when compatibility is not possible, it must return an identifiable incompatibility error.

client-supported profiles ∩ server-supported profiles
empty intersection -> explicit incompatible response

Protocol compatibility therefore requires more than checking whether a request can be deserialized. It must also verify whether the same input still produces consistent results for signature verification, publication sequencing, governance decisions, error codes, and retry behavior. The server must not silently change these semantics to accommodate legacy requests. If an old version can still be read but cannot be safely written, read, write, and query capabilities must be declared separately.

24.3 Resource Schema Version Management

Resource metadata, ResourcePackages, VCs, governance events, and discovery responses record schema or profile versions separately. They are not one shared version: packageVersion in a ResourcePackage describes the resource content version; the schema version of a DID Document describes the document structure; the schema version of a VC describes the credential claims and proof structure; and the event version of a governance event describes its payload and event semantics. A reader should identify each version first, then select the parser and validation rules. It must not use the ResourcePackage version as a substitute for the credential or event schema version.

The handling boundaries for field changes are as follows:

{
  "schemaVersion": "<resource-package-schema>",
  "packageVersion": "<resource-version>",
  "resourceDid": "did:oan:<method-specific-id>",
  "metadataHash": "<hash>",
  "verificationProfile": "<verification-profile>"
}

The example above illustrates field relationships only; the angle-bracketed values are not fixed OAN values. For historical materials, readers should retain the original version, digest, and verification result. Required fields, digest algorithms, signature structures, or status values that cannot be understood must be rejected or placed into an explicitly isolated state; they must not be silently treated as currently valid data.

Readers should identify the schema/profile first, then validate required fields, the digest algorithm, the signature structure, and the status value. When deleting or renaming a field, changing its type, or changing signature coverage, a new profile, migration notes, and negative examples should be produced.

24.4 DID Method Compatibility

Changes to the did:oan method must assess the DID Core data structures, method-specific identifiers, resolver, DID Documents, historical resources, and Root proofs together. A normal resource version upgrade usually keeps the resource DID unchanged and expresses the version change through a new DID Document, ResourcePackage, content digest, control proof, or Root proof. This is a different layer of change from the resolver implementation version or node software version. If method resolution rules, identifier normalization, or control semantics change incompatibly, a strategy must be defined for continued resolution, migration, or deactivation of old DIDs; updating only the implementation version is insufficient.

An unchanged resource DID does not mean that the document content is immutable. The updater must still prove control over the DID and ensure that the new document, ResourcePackage version, VC, and Root proof can validate one another. A Discovery node should select the currently available version according to its supported versions and freshness rules, while retaining traceable relationships to historical versions. Conversely, simply changing a server, SDK, or resolver does not automatically create a new resource version.

24.5 Backward-Compatible and Breaking Changes

Compatibility is determined by verifiable results for old clients, old nodes, historical data, and signature verification behavior, not merely by whether fields can still be deserialized. The assessment should cover at least registration submission, Root platform publication, content distribution platform processing, discovery indexing, governance validation, SDK/Skill invocation, and failure recovery. If any stage interprets the same input as a different resource, version, status, or trust result, it must not be deemed compatible merely because it is parseable.

24.5.1 Compatible Changes

Compatible changes preserve existing required fields, signature semantics, status meanings, and interface success/failure rules. New content should be safely ignorable by old implementations or identifiable through negotiation. Even if the code compiles, results must be verified with old clients, old nodes, and historical data.

• [ ] Existing required fields and error semantics remain valid.
• [ ] Existing signature, status, and version-selection results remain unchanged.
• [ ] Old clients can read or safely ignore the new content.
• [ ] Historical resources, DID Documents, and credentials remain verifiable.

24.5.2 Breaking Changes

Breaking changes include removing or renaming required fields, changing DID or signature semantics, changing resource status, protocol paths, version selection, or governance authorization decisions. Such changes must increase the version, publish the impact, schedule a migration window, and prevent nodes that have not completed migration from mistakenly mixing new and old materials. The following checks should be completed before releasing a breaking change:

• [ ] List affected nodes, clients, SDKs/Skills, DID Documents, ResourcePackages, VCs, Root proofs, and indexes.
• [ ] Specify the read, write, and discovery behavior of the old version during the transition period.
• [ ] Provide before-and-after migration examples, negative examples, rollback data, and retest records.
• [ ] Prevent unmigrated components from interpreting new and old materials as the same valid version.

Before release, freeze the impact scope and identify affected nodes, clients, DID Documents, ResourcePackages, VCs, Root proofs, governance status, and databases. Unmigrated objects must not mix new and old materials. For historical objects that cannot be migrated in one step, explicitly state whether they remain readable, verifiable only, prohibited from updates, or placed in an isolation area, and ensure that discovery results do not display expired or unverified objects as the currently valid version.

24.5.3 Version Identifiers

A version identifier should state its layer, format, source, and comparison rules. For example, specification, protocol, ResourcePackage, schema, Rust crate, npm package, and deployment commit versions cannot substitute for one another. Record the ResourcePackage version separately from resource DID stability, and store both the version and content digest in the evidence.

{
  "specVersion": "<spec>",
  "protocolVersion": "<protocol>",
  "schemaVersion": "<schema>",
  "resourceVersion": "<resource>",
  "implementationCommit": "<commit>",
  "deploymentId": "<deployment>"
}

24.5.4 Migration and Transition Period

The transition period should specify the parallel support range for old and new versions, start and end times, the dual-read/single-write data strategy, node upgrade order, failure rollback, and the conditions for stopping the old version. During the transition period, different versions must not create unexplainable forks of valid versions for the same DID. At the end, retest the registration, Root platform publication, content distribution platform, discovery query, and governance paths. If the old version is read-only, the server must state this clearly in its protocol capability declaration and error responses; callers must not have to infer migration status through trial and error. The migration plan should record at least:

It is recommended to extend read capabilities first, then switch writers, and finally close the old read path. Throughout the process, retain evidence of database migration, rollback, and discovery/publication retesting.

24.6 Specification Changes for Governance Controls

Changes involving node authorization, governance events, resource status, Root proofs, trust decisions, or node protocols must go through a formal proposal, impact assessment, governance approval, release, and effectiveness record. The proposal, approval, code implementation, build artifact, deployment status, and production effectiveness are different types of evidence and must be recorded separately. Signers, verifiers, and affected nodes must be explicit; code being merged or a website being updated cannot substitute for governance effectiveness.

24.6.1 Change Proposal

The proposal should describe the motivation, scope, affected sections and objects, compatibility level, migration plan, test evidence, risks, rollback method, and intended effective time. Proposals involving signatures, authorization, or DID resolution should also list the impact on historical data and third-party nodes.

24.6.2 Governance Approval

Approval should produce a verifiable governance record describing the decision-making authority, approved content, version, scope, conditions, and basis for effectiveness. An ordinary implementation commit, an operational verbal confirmation, or a local configuration on a single node cannot replace a fact that requires governance authorization. The governance approval record should answer at least “who approved it, what was approved, when it takes effect, who verifies it, and which objects are affected”:

approver: <governance-authority>
approvedScope: [protocol, schema, node-policy]
effectiveCondition: <event-or-time>
verificationEvidence: <record>

24.6.3 Release and Effectiveness

The release record associates the specification version, protocol/schema version, code commit, artifact hash, and configuration. Effectiveness should be executed according to the declared time, governance event, or node upgrade condition. Backups, compatibility checks, and conformance retesting must be completed before effectiveness; updating a page does not mean that the protocol has taken effect.

After effectiveness, observe cross-node status, client errors, publication cursors, indexing latency, version distribution, and rollback feasibility to confirm that implementation status matches the specification declaration. If deployment is complete but a Discovery node is still using an old protocol, old schema, or old governance configuration, record it as “deployed but not fully effective” rather than marking it complete directly.

24.6.4 Rollback and Emergency Changes

Emergency changes are limited to fixing security, data integrity, or major availability risks, and must record the reason, authorization, impact scope, and temporary validity period. Rollback must consider the database, publication sequence, governance status, and historical evidence; it is not enough to replace the service binary with an older version. Complete the formal review record afterward. Rollback checks for an emergency change should be performed by object:

Rollback checks should also cover synchronization cursors, caches, and unfinished publication tasks. After an emergency change ends, complete the formal approval and retesting.

24.7 Deprecation and Migration Strategy

Deprecated objects may include interface paths, fields, digest algorithms, protocol versions, node binaries, SDK/Skill packages, or configuration items. A notice should state the object, replacement, support period, affected versions, migration tools, verification method, and service-stop conditions. It should separately specify whether the old object is readable, writable, discoverable, or callable during the transition period. Old interfaces or fields may return explicit deprecation information during the transition period, but must not silently change results. After nodes and clients complete migration, stop the old version according to the recorded conditions and retain audit evidence.

The notice should provide at least before-and-after migration examples, verification commands, the support end time, and a failure rollback entry point.

24.8 Change Records and Release Notes

Each change must record the affected sections, data structures, interfaces, code repositories, database migrations, tests, deployment, rollback, operators, and known impacts. It must also identify the responsible person and deadline when specification clauses and implementation status are inconsistent. Release notes should tell maintainers “what changed, why it changed, who needs to act, and how to verify it,” and should allow them to trace the change identifier to approval, commit, artifact, deployment, and effectiveness checks.

changeId: CHANGE-<id>
scope: [spec, protocol, schema, implementation, deployment]
affectedChapters: []
repositories: []
compatibility: compatible|breaking|deprecated
tests: []
deployment: <commit-or-artifact>
rollback: <procedure>
owners: []
knownImpact: <summary>

The YAML above is an example of a release record, not a fixed OAN configuration. Status checks can proceed in the following order: after code is committed, record the commit identifier; after the build is complete, record the artifact digest; after deployment is complete, record the target environment and service status; after the smoke test passes, record the test result; and only after the protocol, data, and governance effectiveness conditions are satisfied, record effective. If any stage fails, retain the failure reason and rollback action instead of overwriting the status as successful.

24.8.1 Specification Change Records

Record the sections, clauses, version, change type, original text and new intent, compatibility conclusion, approval record, and effective time. Mark errata, clarifications, and specification semantic changes separately so that substantive changes are not presented as textual revisions. Specification change records can be checked using the following fields:

24.8.2 Protocol Change Records

Record changes to routes, requests/responses, status codes, errors, signatures, cursors, version negotiation, and node interoperability, and associate them with protocol tests and the support period for old versions. At minimum, state whether old requests can still register, publish, query, and retry, and what stable error semantics are returned when they are incompatible. Protocol change records should list routes, requests/responses, status codes, errors, signatures, cursors, and negotiation behavior separately, and should include at least one successful old-version example, one successful new-version example, and one incompatible example.

24.8.3 Implementation Change Records

Record the affected repositories, commits, dependencies, Cargo/package versions, database migrations, build artifacts, and deployment environments. If an implementation fix has not yet been synchronized with the specification, clearly state its temporary status and who is responsible for the subsequent specification update. Rust crates, npm packages, website builds, and node binaries must be recorded separately; none of their version numbers may be treated as the version number of the entire OAN implementation. Implementation change records should distinguish the four statuses “code merged,” “build completed,” “deployed,” and “smoke test passed,” so that the existence of a commit is not interpreted as production effectiveness.

24.8.4 Migration Notices and Known Impacts

List the nodes, clients, SDKs/Skills, configurations, and databases that need upgrades. Explain the impact on old resources, historical DIDs, VCs, Root proofs, indexes, and caches, as well as known limitations after migration failure and rollback. Migration notices should list actions and impacts by role and distinguish “must upgrade” from “can continue reading”:

References