This chapter defines the data boundaries, field relationships, deterministic hashing, and recipient-side verification methods for resource metadata and ResourcePackage. Resource metadata describes what a resource is, what it can do, and how it can be connected. ResourcePackage organizes the DID document, metadata, hashes, and root platform trusted publication proof for a specific resource version into a distributable object. A registration submission is the input to the verification process, while a root-platform-verified resource package is the publication product after network-level verification. These three objects are not interchangeable.

This chapter primarily relies on the resource types, serialization implementation, and resource package validation code in oan-protocol-common. The current registration payload schema only provides object-level entry constraints; the semantics of individual fields are jointly determined by the protocol types and validation logic. Where the schema, implementation, and deployment configuration differ, the applicable version and the difference should be stated. A single example must not be treated as mandatory behavior for every implementation.

6.1 Resource Metadata Schema

In the Rust implementation, resource metadata is represented by ResourceMetadata. Its core fields are as follows:

These fields may be exposed for registration, distribution, and discovery, but control private keys, internal access credentials, and operational details that should not be public must not be placed in the metadata. Unknown extension fields may be retained only when they do not change the meaning of core fields, the hash input, or the verification result. A recipient should reject core-field type errors, a missing resource DID, or unsupported enum values.

The following fragment shows the field relationships in a ResourceMetadata instance. The hash values are examples and must not be used directly in production materials. During metadata hash computation, packageHash and metadataHash must first be cleared and then populated with the computed results.

{
  "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "resourceType": "skill",
  "subjectType": "skill",
  "publisherDid": "did:oan:ORLG:8LcR3Vn5YpQw2Tx7Mb9Zd4Fa6GhKsEuJ",
  "subjectDid": "did:oan:DVLG:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz",
  "name": "Repository Structure Summary",
  "description": "Summarizes the structure of a code repository.",
  "capabilityTags": ["code-repository", "project-structure-summary"],
  "authorizedDomains": ["public"],
  "protocolBindings": [],
  "services": [],
  "lifecycleState": "active",
  "packageVersion": "1.0.0",
  "packageHash": "sha256:example-package",
  "metadataHash": "sha256:example-metadata",
  "hashAlgorithm": "sha256",
  "updatedAt": "2026-09-09T08:30:00Z"
}

6.2 Required and Optional Fields

The structurally required fields of ResourcePackage include packageVersion, resourceDid, resourceType, didDocument, didDocumentHash, metadataHash, packageHash, hashAlgorithm, metadata, rootProof, and createdAt. In the metadata, the resource DID, resource type, subject type, package version, three key hashes, and hash algorithm are the core fields for forming a verifiable publication object. Capability tags, authorized domains, protocol bindings, and service endpoints may be empty arrays or may be undeclared for a given resource type, but their omission must not be presented as evidence that the resource has the corresponding capability.

The four resource types share common identity, description, version, integrity, and governance fields. An agent service generally needs capability descriptions, use cases, interaction protocols, and service endpoints. A skill package needs package entry points, installation or loading information, and dependencies. An MCP server needs transport methods, tool or resource inventories, and authentication requirements. A tool/API needs operations, parameters, outputs, and invocation constraints. Exact requiredness is determined by the protocol model for the applicable version; web form inputs cannot directly replace the underlying schema.

When a field required by the protocol is empty, the recipient must reject the object. A missing optional field is handled as “undeclared”. Unknown extension fields may be retained in compatibility mode, but they must not be used for permission decisions that the recipient cannot interpret. The registration service node should perform these checks before registration, and the recipient of a ResourcePackage should perform them again.

The four resource types share the resource DID, resource type, subject type, description, capability tags, version, authorized domains, and integrity fields, but the resource type determines which capability descriptions and endpoint information have practical meaning. When fields are missing, the recipient should distinguish “undeclared” from “structurally incomplete”. For example, no optional service endpoint may mean that no invocation entry point has yet been declared, while a missing resourceDid, resource type, DID document, or resource package hash prevents the formation of a verifiable resource package.

6.3 Resource Type and Subject Type Constraints

The resource type must remain consistent with the semantic encoding of did:oan: agent_service corresponds to AG, skill to SK, mcp_server to MC, and tool_api to TL. In current resource package validation, resourceType and subjectType in the resource metadata must be identical, and both should correspond to the subject code in the resource DID. Infrastructure nodes, organizations, and developers may be identified as method-level identity objects, but a node DID must not be directly used as a product resource DID.

A subject may control multiple resource DIDs, and one resource provider may operate multiple resources. The identity boundaries between the subject DID, resource DID, and node DID are not merged by relationship fields. A verifier must reject a resource package when its resource type, subject type, DID document id, or package metadata is inconsistent.

6.4 Name, Description, Tags, and Use Cases

The name and description are public claims by the resource provider about the resource’s capabilities. Capability tags and use cases are used for registration recommendations, semantic governance, and discovery queries. Tags should preferably reference identifiers in the root platform capability tag tree; an extended tag should state its source or namespace. Natural language may use Chinese, English, or another declared language, but field types and array structures must remain stable. HTML, scripts, or unparseable objects must not be mixed into these fields. A detailed description does not mean that the capability has been verified, and relevance ranking is not proof of control or business quality.

The name and description are public claims by the resource provider about the resource’s capabilities. Capability tags and use cases are used for registration recommendations, semantic governance, and discovery queries. Tags should preferably reference identifiers in the root platform capability tag tree; an extended tag should state its source or namespace. Natural language may use Chinese, English, or another declared language, but field types and array structures must remain stable. HTML, scripts, or unparseable objects must not be placed in text fields.

A more detailed description or use case does not mean that the capability has been verified. Relevance ranking by a discovery service node is also not proof of control, endpoint availability, or business quality. Length, quantity, and content filtering should be specified by deployment or conformity configuration and enforced before registration and indexing.

When capability tags and use cases enter the discovery process, they may serve both as structured conditions and as semantic retrieval text, while the original values and their sources should be retained in the result. For example, a query such as “I need a tool that can inspect a code repository and summarize its project structure” may match the relevant capability description and use case. Whether the resource can be invoked still requires checking the resource DID, publication proof, endpoint, and credential requirements. A tag match is evidence of relevance, not proof of resource control or business effectiveness.

6.5 Semantic Tags and Protocol Bindings

capabilityTags expresses the resource capability classification, while authorizedDomains expresses the scope of propagation and discovery permissions. They cannot substitute for one another. A binding object in protocolBindings must at least state the protocol name and may include a version, transport method, serviceRef, and schemaRef. A protocol binding describes how to connect; it does not automatically grant invocation permission. A registration service node may use these fields to recommend tags, and a discovery service node may use them for structured or semantic retrieval, but returned results must still retain their source and verification status.

capabilityTags expresses the resource capability classification, while authorizedDomains expresses the scope of propagation and discovery permissions. They cannot substitute for one another. A binding object in protocolBindings must at least state the protocol name and may include a version, transport method, serviceRef, and schemaRef. A protocol binding describes how to connect; it does not automatically grant invocation permission. The tag-tree version, tag identifier, and aliases should retain their source so that different nodes can interpret the same tag.

A registration service node may provide recommendations based on capability descriptions and the tag tree. A discovery service node may use them for structured or semantic retrieval, but externally returned results must still retain the original tags, protocol bindings, source, and verification status. A tag match without a root platform publication proof must not enter the trusted discovery result set.

The minimum expression of a protocol binding may be written as the following object. serviceRef and schemaRef are internal resource references or external schema references; they must not be interpreted as new identities:

{
  "id": "mcp-http",
  "protocol": "MCP",
  "version": "2025-06-18",
  "transport": "streamable-http",
  "serviceRef": "#mcp-service",
  "schemaRef": "https://example.invalid/schema/mcp.json"
}

6.6 Service Endpoints and Invocation Requirements

Resource endpoints are expressed as a service endpoint array. The core structure includes an endpoint ID, service type, and serviceEndpoint, and may include a version, protocol, server type, and port. An endpoint may be an agent interaction entry point, an MCP service entry point, a tool API address, a resource package address, or a protocol description address. The endpoint type and protocol should explain its purpose, and version or authentication differences between multiple endpoints should be explicit. An authentication declaration may express the credential type, issuer, scope, presentation method, or invocation prerequisite, but it is only a public statement of invocation requirements. The existence of an endpoint or HTTP reachability does not mean that the caller has been granted access. Sensitive tokens, private keys, and internal network credentials must not be published as public metadata.

6.7 Resource Versions and Compatibility Fields

packageVersion identifies the resource package version. A version in the resource description or a version in a protocol binding may express a resource capability version or protocol version; they must not be substituted for one another without explanation. previousVersion, version constraints, or release notes may establish an update chain and compatibility relationship, but a version string alone does not prove the source of the content. Every version must be bound to the resource DID, DID document hash, metadata hash, resource package hash, and hash algorithm. A new version under the same resource DID should enter the verification process through a new resource package and control proof.

Version comparison should at least keep the resource package version, protocol version, and resource lifecycle separate:

The same version string does not mean that the content is identical. A recipient should still check the resource DID, three classes of hashes, root platform proof, and governance state. If content changes while an old hash is retained, the recipient should treat it as an integrity failure.

6.8 Package Hash and Metadata Hash

The current implementation separately computes the DID document hash, resource metadata hash, and resource package hash. A hash value is expressed with an algorithm prefix, such as sha256:<digest>. hashAlgorithm must be consistent with the algorithm prefix in the hash references. Before computing the metadata hash, the metadata’s own metadataHash and packageHash are cleared to avoid circular dependencies. The resource package hash is computed only from fixed declarations such as the package version, resource DID, resource type, DID document hash, metadata hash, and hash algorithm. A verifier should recompute all three hashes using the same cryptographic suite and serialization method. A matching hash alone does not prove control, node authorization, or endpoint availability.

The input to the resource package hash is not a recursive serialization of the entire resource package. It is the set of package declaration fields explicitly selected by the current implementation:

{
  "packageVersion": "1.0.0",
  "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "resourceType": "skill",
  "didDocumentHash": "sha256:example-did-document",
  "metadataHash": "sha256:example-metadata",
  "hashAlgorithm": "sha256"
}

This input illustrates the field boundary of verify_package_hash. The actual digest must be computed by the implementation using the unified cryptographic suite; the example digest must not be written into a production package. The metadata hash is computed over ResourceMetadata after its two own hash fields have been cleared. The two input sets must not be mixed.

6.9 Canonical Serialization and Deterministic Hashing

Deterministic hashing requires implementations to use the same field names, enum serialization, array order, time format, null handling, and character encoding. The current Rust implementation serializes the object with serde and then passes it to a unified hash function. Cross-language implementations must not change field names, add arbitrary default values, or sort arrays before hashing unless the specification version explicitly requires it. The metadata hash and package hash must not include their own output fields in the input again. If canonicalization fails, an object cannot be serialized, or the algorithm is unsupported, construction should stop and return an error.

When reproducing the process across languages, the object before hashing should be recorded so that “different fields” and “different serialization” can be distinguished:

ResourceMetadata for hashing
  -> clear metadataHash and packageHash
  -> serialize with protocol field names and stable enum values
  -> hash with the selected crypto suite
  -> write metadataHash back to the package

Package hash input
  -> packageVersion, resourceDid, resourceType
  -> didDocumentHash, metadataHash, hashAlgorithm
  -> serialize and hash

If only the description, tag order, authorized domains, or time field in the metadata changes, the canonicalized metadata input changes and the recipient should obtain a different metadata hash. If only the computed result is written back without changing any other input, the existing hash must not change.

6.10 ResourcePackage Construction Rules

The construction order for ResourcePackage is: determine the resource DID, resource type, DID document, and metadata; compute the DID document hash and metadata hash; compute the resource package hash; organize the version, hashes, lifecycle state, and authorized-domain declarations; have the resource controller submit the control proof; and let the registration service node and root platform perform their respective registration and publication duties. A root platform trusted publication proof can be produced only after the root platform has completed verification. A client must not construct one in advance as if publication had already occurred.

The responsibility boundaries among resource metadata, the DID document, the resource package, the root platform trusted publication proof, and the discovery index record are as follows:

The relationship between construction and publication can be represented as follows:

The construction process can be represented as a reviewable dependency chain:

The registration processing and root platform verification shown in the diagrams belong to the resource network stage and must not be written into an ordinary resource package constructed by the client in advance. Each step should retain the input version and output hash. If any input changes, all subsequent dependent steps must be performed again.

6.10.1 Input Materials

Input materials include the resource DID, resource type, DID document, resource metadata, resource package version, hash algorithm, resource control proof, and any necessary registration credentials or source references. The DID document id, metadata resourceDid, package resourceDid, and the DID targeted by the control challenge must be consistent. The resource type and subject type must be consistent with the semantic encoding of the DID.

6.10.2 Field Canonicalization

The constructor should use protocol field names and deterministic serialization rules, represent time as a parseable UTC value, and keep array order and enum values stable. Before computing the metadata hash, clear metadataHash and packageHash in the metadata. When computing the package hash, include only the specified package declaration fields.

These fields are mapped to HTTP JSON through serde; a separate interface schema is not automatically generated at compile time. ResourceRegistrationSubmission.didDocument uses the DID document type, while metadata uses dynamic JSON. ResourcePackage.metadata uses the resource metadata type, and rootProof uses the root platform proof type. The recipient therefore needs both Rust-type-based deserialization and business validation of resource types, hashes, and proofs. Successful deserialization does not mean that the object can be published.

6.10.3 Hash Computation

Compute the DID document hash, metadata hash, and resource package hash in sequence, and write the algorithm prefix into the corresponding fields. After hashes are populated, none of the other fields participating in the hash may be changed. A change in any recomputed result indicates that the content of the current version has changed.

6.10.4 Signature and Proof Generation

The resource controller signs the control challenge and the prescribed resource-control materials. A registration service node may issue a registration credential for the registration fact. After checking node authorization, the control proof, hashes, and publication conditions, the root platform generates a root platform trusted publication proof. The issuer, verification method, target DID, purpose, and covered hashes of each proof must be verifiable.

6.10.5 Post-construction Validation

After construction, check resource type consistency, metadata consistency, the DID document hash, metadata hash, resource package hash, and root platform statement binding in sequence. A failure in any check must prevent the object from being marked distributable or trusted-published. A failed object may be retained as local diagnostic material, but it should not enter a public index.

The post-construction check result can be recorded as a machine-readable diagnostic summary:

{
  "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "packageVersion": "1.0.0",
  "checks": [
    { "name": "resource_type_consistency", "status": "passed" },
    { "name": "metadata_consistency", "status": "passed" },
    { "name": "did_document_hash", "status": "passed" },
    { "name": "metadata_hash", "status": "passed" },
    { "name": "package_hash", "status": "passed" },
    { "name": "root_claim_binding", "status": "passed" }
  ],
  "publishable": true
}

publishable means only that the local object passed the current package checks. It does not replace acceptance by a registration service node or publication by the root platform. If any check fails, the diagnostic result should include the corresponding error category, and the package must not enter trusted distribution or a discovery index.

6.11 Structure of a Root-Platform-Verified ResourcePackage

The resource package after root platform verification is still based on the DID document, resource metadata, and hashes provided by the resource controller, but it adds or binds the root platform’s verification result for that specific resource version. The root platform DID, packageClaims, signature or data-integrity proof in rootProof, together with any necessary announcement-event reference, expresses which facts the root platform has checked and accepted. The publication sequence, publication time, and synchronization cursor belong to the publication or propagation layer and must not be written back as original claims by the resource provider.

6.11.1 Resource Identity Section

The resource identity section includes resourceDid, resourceType, the DID document in the package, and didDocumentHash. The recipient should check that the package fields are consistent with the DID document id, resolve did:oan, and verify the resource-type mapping. A valid identity section only means that the package is bound to a resolvable resource DID; it does not mean that the resource has been published by the root platform.

6.11.2 Resource Metadata Section

The resource metadata section includes the name, description, capability tags, use cases, authorized domains, protocol bindings, service endpoints, lifecycle, and version information. The recipient should check that the metadata hash, resource type, resource DID, package version, authorized domains, and lifecycle are consistent with the declarations outside the package, and should retain the metadata source and update time.

6.11.3 Root Platform Verification Proof

The root platform verification proof must at least associate the root platform DID, resource DID, resource type, package version, DID document hash, metadata hash, package hash, hash algorithm, lifecycle state, and authorized domains. If packageClaims is inconsistent with the package contents, the proof signature cannot be verified, or the proof source is outside the trusted scope, the package must not be treated as a root-platform-verified resource package.

6.11.4 Fields Required for Distribution and Indexing

Distribution and indexing require at least the resource DID, resource type, package version, three classes of hashes, root platform proof, lifecycle state, authorized domains, source reference, and publication or synchronization cursor. A discovery service node should also record the local receipt time, verification time, current synchronization position, and rejection reason, so that an old snapshot, indexing lag, or cross-node inconsistency can be explained.

6.12 ResourcePackage Integrity and Provenance Verification

The recipient should first verify the structure and resource identity, then verify the DID document hash, metadata hash, resource package hash, field consistency, and root platform proof in that order. Finally, it should combine lifecycle, authorized domain, version, and governance state to decide whether the object may be written to a distribution cache or discovery index. A hash or proof failure must prevent the object from entering the trusted read model. Temporary network unavailability may place it in a pending-retry state, but an object with incomplete verification must not be marked as published.

The recipient may classify verification results into three categories: “passed”, “rejected”, and “pending retry”:

“Pending retry” is not a verified state. Even when the JSON structure of a package is correct, if the root platform proof or a necessary source cannot be confirmed, the recipient may retain only an incomplete state.

6.13 ResourcePackage Provenance Chain and Attribution

The resource provenance chain contains at least five classes of facts: the resource controller produces the DID document, metadata, and control proof; the registration service node produces the registration acceptance and registration credential; the root platform produces the resource-version acceptance, root platform trusted publication proof, and publication reference; the content distribution platform forwards or caches materials whose propagation is permitted by the root platform; and the discovery service node produces the local verification and indexing record. Each fact should identify the source subject, target resource DID, version, time or cursor, and preserve its signature or hash association.

The provenance chain can be read in five stages: “claim, registration, publication, transport, and indexing”:

Resource controller
  -> DID document, resource metadata, control proof
Registration service node
  -> registration record, registration credential
Root platform
  -> acceptance record, root platform trusted publication proof, publication reference
Content distribution platform
  -> transport or cache record for verified materials
Discovery service node
  -> local validation, synchronization position, and discovery index record

Each later stage may add facts about its own processing, but it cannot issue a proof that belongs to an earlier stage. For example, an index record from a discovery service node may show that the node verified and stored materials for a version; it cannot replace the resource controller’s control proof or the root platform’s publication proof.

6.13.1 Resource Controller Provenance

Resource controller provenance is determined by the DID document’s control relationship, the resource control proof, and its signature verification method. publisherDid or subjectDid may supplement a business relationship, but cannot replace the control proof. The recipient should check the resource party’s claim against the current DID document and proof together.

6.13.2 Registration Service Node Provenance

Registration service node provenance is expressed by the receipt record for the registration request, the node DID, node authorization materials, the registration credential, and the processing state. The scope of a registration credential is the registration fact; it does not automatically prove that the root platform has accepted the resource or that a discovery service node has indexed it.

6.13.3 Root Platform Publication Provenance

Root platform publication provenance is expressed by the root platform DID, root platform trusted publication proof, resource package declarations, and publication or announcement references. The root platform proof must be bound to a specific resource version and its hashes. A proof for another version under the same resource DID cannot be reused directly.

6.13.4 Provenance Chain Verification

Provenance-chain verification requires checking the control proof, registration credential, root platform trusted publication proof, and distribution record layer by layer. A content distribution platform proves only transport or caching behavior, while a discovery service node proves only local retrieval, validation, and indexing behavior. A missing layer must be reflected in the response; the existence of a later layer must not conceal the failure of an earlier one.

6.14 Package Size, Content Limits, and Validation Strategy

Size, length, nesting depth, number of endpoints, number of tags, and number of protocol bindings should be specified by deployment or conformity configuration and enforced by the registration service node and ResourcePackage recipient using the same limits or limits no lower than the network requirements. When the current schema does not define a unified numerical business limit, this chapter must not invent a fixed number. The implementation must return an identifiable error when a limit is exceeded, preventing oversized text, deeply nested structures, or large numbers of endpoints from exhausting parsing, indexing, and hashing resources. Limit checks must occur before hash computation, so that truncation, omission, or automatic compression cannot produce a different hash.

Limit checks should be applied to the original input, and the failure reason should be associated with a field path rather than silently truncating the content:

{
  "validation": "rejected",
  "errors": [
    {
      "path": "metadata.capabilityTags",
      "code": "limit_exceeded",
      "message": "capability tag count exceeds the active profile"
    }
  ],
  "hashingStarted": false
}

The limit values in the example are determined by the actual deployment configuration. Once input has been truncated, a field has been discarded, or an array has been automatically reordered, the object being hashed has changed and the original signature or hash cannot continue to be used.

6.15 Schema Evolution and Backward Compatibility

Schema evolution should distinguish the addition of an optional field, a change to existing semantics, field removal, and a change to the hash input or signature coverage. If a new field does not affect parsing by older implementations or existing hash rules, it may be introduced through a versioned extension. If it changes resource identity, resource type, version, hash input, root platform statement, or the verification process, the schema or protocol version must be advanced and the behavior of older nodes must be stated. An older node may ignore an unknown optional field, but it must not silently discard a field covered by a signed object when recomputing it. An unknown required field, an unrecognized hash algorithm, or an unverifiable proof should cause rejection or entry into a compatibility-pending state.

This section specifies only the effects of schema changes on parsing and integrity validation. The responsibility boundaries of resource metadata, the DID document, the resource package, the root platform trusted publication proof, and the discovery index record are described in Sections 6.1, 6.4, 6.10 through 6.13, and Chapters 9 and 10 respectively. A schema-version change does not automatically change resource control, publication state, or discovery visibility. The recipient must still recompute the relevant hashes according to the established validation order and retain the reason for any failure.

References