This chapter treats external protocol integration as a traceable transformation process: first identify the external object and its version; then map verifiable fields to OpenAgenet (OAN) resource metadata or a resource package; next verify resource control, registration credentials, the Root platform’s Root proof, and governance status separately; and finally explain to the caller which information can be used for discovery and which information must still be rechecked before invocation. An adapter must preserve the external original, source, summary, and transformation version, and must not treat a transformed summary directly as an OAN trusted publication fact.

A mapping result answers “how the external system describes and connects to this resource”; it does not directly answer “whether this resource has been authorized by the OAN network.” The latter determination must return to the OAN DID, signatures, registration credentials, Root proof, and governance status.

21.1 W3C DID Core and did:oan

An adapter should store common DID Core fields and did:oan method fields in separate layers. Common fields allow DID tools to understand the document, while OAN fields express the resource type, capabilities, version, resource package, and publication relationships. The following object is only an example of a mapping record, not a new DID Document:

{
  "source": {"type": "did-document", "version": "did-core-compatible"},
  "oan": {"method": "did:oan", "resourceDid": "did:oan:SKDM:<identifier>"},
  "mapping": {
    "preserved": ["id", "verificationMethod", "service"],
    "mapped": ["resourceType", "capabilityTags", "protocolBindings"]
  }
}

This record only describes the transformation process. did:oan uses the common identity and service expression mechanisms of DID Core, and supplements the information required for resource discovery and publication through OAN resource metadata, resource packages, and associated proofs.

21.1.1 DID Core Data Structure Correspondence

The id, verificationMethod, control relationships, and service in a DID Document correspond to the common data model of DID Core. OAN resource types, capability tags, use cases, versions, resource package references, and publication-proof associations belong to the OAN resource model or method extensions. An adapter should preserve the original fields and original paths, and must not disguise OAN extension fields as DID Core standard fields.

21.1.2 did:oan Method Extensions

The did:oan method extensions express the resource subject, resource type, capability set, endpoints, protocol bindings, version references, and publication-evidence associations. Method extensions must specify field types, required conditions, normalization rules, and signature coverage. Changes to extension fields should enter DID Document or resource package version management.

The method-extension checks proceed in the following order:

1. Parse the method name and method-specific identifier.
2. Check the resource type or node role against the subject code.
3. Check metadata, services, versions, and resource package references.
4. Independently verify the control proof, hash, registration VC, and Root proof.

An extension that affects signature coverage, resource type, version selection, or governance decisions should be treated as a breaking change and entered into the change record in Chapter 24.

21.1.3 Resolution Behavior

A resolver receives the complete did:oan, first validates the method name and method-specific identifier, then reads the corresponding DID Document and verifies its structure, control relationship, status, and version. Not found, method unsupported, invalid document, missing proof, and unknown status should be returned separately; errors must not be concealed by an empty document or the most recent cache.

21.1.4 Interoperability Boundaries

DID Core interoperability ensures that the common identity structure can be understood; it does not ensure that an external resolver understands OAN resource semantics, the Root platform’s Root proof, or governance status. An external system can read the DID Document and obtain entry points, but before invocation it must still verify the resource version, publication evidence, and endpoint according to OAN rules.

An interoperability report should record format interoperability and OAN semantic interoperability separately. The former proves that an external resolver can read common fields; the latter proves that the caller can understand the resource type, capabilities, version, resource package, and publication evidence. They must not be merged into a single “compatible” conclusion.

21.2 A2A Agent Card Mapping

The relationship between OAN and an A2A Agent Card can be distinguished as “network-level resource discovery” and “service-level invocation description”: OAN provides stable identity, source, version, and governance association through the DID Document, resource metadata, and resource package; an A2A Agent Card describes the agent service provider, supported interaction entry points, capabilities, skills, input and output modes, and security declarations. The two can reference each other, but a mapping does not change the identity, signature, or authorization semantics of either side.

The capability descriptions, use cases, endpoints, and protocol bindings in an OAN resource profile can provide a trusted discovery entry point for an A2A Agent Card. For reverse integration, an Agent Card can only serve as a source for a registration draft or supplementary description; the resource controller must still generate and sign the resource materials through the OAN process. Detailed invocation flows are determined by A2A, MCP, a tool API, or the resource’s own protocol.

21.2.1 Capability Description Mapping

OAN’s capabilityTags, capabilityDescription, and use-case information can be mapped to the skills, skill names, descriptions, and example tasks of an A2A Agent Card. During mapping, preserve the tag-tree path, original text, resource package version, and source. The semantic matching result from an OAN Discovery node can help locate candidate resources, but it cannot prove that a resource is authorized or necessarily possesses the declared capability.

It is recommended to preserve both normalized tags and the original description:

{
  "tag": "code.repository",
  "sourcePath": "skills[0].name",
  "sourceVersion": "1.0",
  "resourcePackageVersion": "1.0.0"
}

Normalized tags serve filtering and semantic governance; the original text serves explanation and review.

21.2.2 Use-Case and Skill Mapping

OAN use-case fields and skill package information can be used to generate the skill summary, example tasks, and input and output descriptions of an Agent Card. The generated result should retain the resource package version and field sources. If an external Card provides only a summary, reverse registration can produce only a resource description requiring verification; it cannot fill in control, version, endpoint, or governance information that OAN does not contain.

21.2.3 Service Endpoint Mapping

Service endpoints, protocol types, transport methods, and authentication requirements in an OAN DID Document or resource package can be mapped to the supportedInterfaces, protocol bindings, and security declarations of an Agent Card. Endpoint mapping only provides connection-preparation information and does not mean that the endpoint is available; the caller must still perform TLS, authentication, version, status, and business-authorization checks. Endpoint mappings can record “entry point, protocol, transport, authentication, version, and status” item by item. When any item comes from an external description, retain the original path or digest so that it can be checked again before invocation.

21.2.4 Identity, Signature, and Trusted-Evidence Mapping

The provider, signature, or security declaration of an Agent Card can be stored as external input, but the OAN resource identity is determined by did:oan and its control relationship. The overall signature of an Agent Card proves the Card’s content and its publisher’s statement; a registration VC, the Root platform’s Root proof, and governance status prove different facts in the OAN process and must be retained separately rather than replacing one another.

Identity and evidence mappings should be stored in layers:

• The resource control relationship answers “who can control this DID.”
• The Agent Card or external declaration answers “how does the external system describe this resource.”
• The registration VC answers “what registration fact did the Registrar node declare.”
• The Root proof answers “what content did the Root platform verify and publish.”

21.3 MCP Resource and Server Metadata Mapping

OAN treats an MCP service as a discoverable resource. Mapping should record three layers: “server, tool, and invocation.” The server layer describes identity, protocol version, transport, and endpoint; the tool layer describes the tool or resource inventory, names, descriptions, and input schemas; the invocation layer describes sessions, authentication, and error constraints. The resource package should preserve the inventory original or a stable reference, version, and hash; the discovery index may store only a retrieval summary. A successful MCP initialization only means that the service completed one protocol interaction; it does not mean that the Root platform has verified and published the resource.

21.3.1 MCP Server Mapping

The name, description, protocol version, transport, endpoint, and server capabilities of an MCP Server are mapped to the metadata of an OAN MCP service resource. The server DID, control proof, resource version, resource package hash, and Root proof are stored independently to distinguish “server self-description” from “network-verified publication.” Each tool record should also retain its server and resource package version to avoid deduplicating across services solely by tool name.

21.3.2 Tool Definition Mapping

MCP tool names, descriptions, input schemas, and available capabilities can be mapped to OAN tool entries, capability descriptions, and tags. A tool entry should include its server, resource package version, content digest, and location in the original inventory. Identical tool names do not mean that the tools belong to the same controller. A discovery index may use summary fields, but the caller should be able to return to the complete inventory to verify the tool boundary.

21.3.3 Input and Output Constraint Mapping

MCP input schemas, result structures, and error constraints are mapped to OAN input and output descriptions, while preserving the original schema, media type, version, and hash. If mapping fails or fields are incomplete, the resource may be registered as incompletely described, but the caller must not be told that the constraints have been verified. Input and output mappings can use a schema version and digest to establish a stable reference. When field types, required relationships, enumeration values, or error structures change, treat the change as a new description version rather than merely updating display text.

21.3.4 Invocation and Authentication Information Mapping

MCP transport, session establishment, authentication requirements, and pre-invocation conditions can form part of OAN service information and support connection preparation after discovery. OAN publication proof proves only the declared materials and their source; it cannot grant business permissions to an MCP server or guarantee session success. Invocation and authentication mappings should distinguish “access conditions visible during discovery” from “permissions granted by the service at runtime.” OAN registers and verifies declarations and their sources, but does not replace the business authentication of an MCP service or tool API.

21.4 Tool and API Description Mapping

OpenAPI mapping should establish stable entries at the path-and-operation level:

operationId: searchRepository
source: openapi.yaml#/paths/~1repositories~1search/get
oanResourceDid: did:oan:TLDM:<identifier>
schemaHash: sha256:<value>

A normalized summary can be used for discovery and deduplication; the original document is used for pre-invocation review.

A tool API should use the path and operation as the minimum audit unit and retain at least the operationId, original document path, server endpoint, schema version, authentication requirements, and digest. The normalized summary is used for discovery and deduplication; the original document is used for pre-invocation review. A readable document does not mean that the interface is callable.

21.5 VC and VP Ecosystem Interoperability

VC/VP processing should follow the sequence “parse → cryptographic verification → status check → trust-policy decision.” Each failure must produce a clear intermediate status; “valid JSON” must not be displayed directly as “trusted.”

An adapter can parse the subject, issuer, credential type, validity period, status, and proof materials of an external VC/VP, and retain the original object and verification result. Being parseable only means that the format is readable; acceptance also depends on issuer authorization, control relationship, governance status, and the OAN trust policy. For input whose status information cannot be obtained, whose signature verification fails, or whose issuer relationship is unclear, retain the failure reason and route it to rejection or manual review.

21.6 External Organization and Platform Identity Mapping

An external organization, platform account, domain name, or its DID can be stored as associated information for a resource provider, operator, delegate, or endpoint host, but the relationship type, evidence source, responsibility scope, and validity period should be recorded. A domain name, enterprise account, platform authentication record, and resource-control DID are not the same field. An external account name cannot replace control of the resource DID, and domain or platform authentication cannot directly create eligibility for Root platform publication.

21.7 External Credential and Trust-Evidence Mapping

An external evidence record is recommended to include issuer, subject, credentialType, issuedAt, expiresAt, statusSource, sourceHash, verifiedAt, and verifier. When no status endpoint is available, record “status not checked” rather than assuming validity. OAN treats it as supplementary evidence, while node authorization, resource control, and Root platform publication are still determined by their respective OAN evidence chains.

21.8 Field Source, Version, and Hash Requirements

A field source can be represented by the following audit record. agent-card.json, the digest, and the time in the example are placeholder values:

{
  "field": "capabilityTags[0]",
  "source": "agent-card.json#/skills/0",
  "sourceHash": "sha256:<value>",
  "mappingVersion": "oan-a2a-v1",
  "verifiedAt": "<timestamp>"
}

Each mapped field should record the source object, source path, original version, normalized version, signing subject, and content digest. The normalization operation should be reproducible. When sorting, case conversion, aliases, or field truncation changes the digest, the digest and mapping version must be updated, and the old result must be retained for auditing.

21.9 Compatibility Profiles and Migration Paths

An interoperability profile should specify the supported DID, A2A Agent Card, MCP, and OpenAPI versions; required and optional fields; signature algorithms; transport; error policy; and migration method. During migration, first retain the original evidence, read the old and new profiles in parallel, check field digests and signature boundaries, and then switch to single-write operation. If migration fails, return to the old profile without overwriting the sole source. The profile itself should have a name and version so that callers know which set of mapping rules is being used.

21.10 External Protocol Capability Negotiation

Negotiation results can be classified as compatible, partially-compatible, or incompatible, while also reporting the common protocols, versions, transports, and security capabilities together with unmet capabilities:

{
  "result": "partially-compatible",
  "commonProtocols": ["https"],
  "missing": ["required-auth-scheme"]
}

The client or adapter declares the protocols, versions, transports, and security capabilities it supports, and selects an available profile based on the intersection of both sides. When no common capability exists, return an explicit incompatibility result. Successful negotiation only means that the format and interaction capabilities are available; resource identity, publication evidence, governance status, and business permissions must still be verified separately.

21.11 External Signature and Evidence Retention

An adapter’s output should store the original text, normalized digest, external signature, and OAN signature separately, and assign a source identifier to each item of material. When repackaging or forwarding, do not retain only the transformed object; it should at least be possible to answer “what was the original object, who signed it, what did they sign, did the transformation change the content, and which OAN party signed again.” During adaptation, retain external signatures, credential references, original objects, versions, digests, verification time, verifier, and failure reasons. When re-encoding or generating an OAN resource package, do not lose the boundary between external materials and the OAN control signature; the two types of signature separately describe the facts they cover.

The adapter output should store the original object, normalized object, external signature, resource-control signature, registration VC, and Root proof separately. An audit should be able to answer: what was the original object, who signed it, what did they sign, did the transformation change the content, which party signed again, and when did verification occur.

References