This chapter explains how OpenAgenet (OAN) governs capability tags, aliases, authorization domains, and semantic configuration, and how it uses semantic information such as resource names, descriptions, use cases, and protocol bindings for registration recommendations, structured filtering, text retrieval, semantic ranking, and result explanation. It also draws a clear boundary between semantic relevance and identity, control, publication proof, lifecycle, and governance status, ensuring that semantic discovery improves resource matching without changing trusted publication or authorization decisions.

12.1 Semantic Model and Capability Vocabulary

In OpenAgenet (OAN), the semantic model separates what a resource “can do” into several types of information that can be reused by registration and discovery: resource names and descriptions provide natural-language context, capability tags provide relatively stable classification keys, use cases describe applicable tasks, protocol bindings describe interaction methods, and resource types describe object categories. These elements jointly participate in recommendation and retrieval, but they cover different kinds of facts. The capability tag tree answers “which capability category does this term belong to,” the resource package answers “which capabilities does a specific resource declare,” and the DID Document and credential materials answer “who controls the resource, whether it has completed registration, and whether the publication fact can be verified.”

Therefore, semantic matching results should be understood as candidate discovery clues rather than trusted conclusions. A Registrar node may generate tag recommendations based on names, descriptions, use cases, and protocols, and the provider may confirm them before they are written into Resource Metadata. A Discovery node may reuse these fields for filtering, lexical retrieval, or semantic ranking. No matter how high the recommendation score is, it cannot replace control verification, registration credentials, Root proof, lifecycle status, or authorization-domain checks.

12.2 Root Platform-Managed Capability Tag Tree

The capability tag tree is published by the Root platform together with its version and snapshot for use as shared semantic material by registration recommenders and Discovery nodes. The tag tree object in the current public implementation contains version, an optional snapshotHash, and tags; each tag node contains at least a stable id and a display label, and may also contain aliases and recursive children. The following is a minimal example organized according to this data structure; all values are illustrative placeholders:

{
  "version": 1,
  "snapshotHash": "sha256:example",
  "tags": [
    {
      "id": "code.repository.search",
      "label": "Code Repository Search",
      "aliases": ["Search Codebases"],
      "children": []
    }
  ]
}

The structure of the tag tree organizes semantics and makes queries reproducible; it is not a resource authorization list. After the Root platform adds or adjusts tags, registration recommendations may use the new version, and Discovery nodes may rebuild their indexes accordingly. The original descriptions and original tags submitted by existing resources must not be silently rewritten because the tag tree changed. If a node uses an older snapshot, it should record the version used so that differences in recommendations or discovery results can be explained.

12.2.1 Tag Tree Organization

The capability tag tree uses the organization of “stable identifier + parent-child relationship + display name + vocabulary version.” A tree node expresses a capability category; it does not directly express whether a resource has been registered, published, or trusted. A resource may be associated with multiple leaf nodes or only with a higher-level node, but the Registrar node should store the tags actually selected by the resource rather than only the recommended path.

{
  "id": "code.repository.search",
  "parent": "developer.tools",
  "labels": {"zh-CN": "代码仓库检索", "en-US": "Code Repository Search"},
  "vocabularyVersion": "v1"
}

12.2.2 Tag Identifiers and Hierarchical Relationships

The tag ID is a cross-node association key. Parent-child relationships organize the retrieval scope, but capability inheritance must not be inferred without vocabulary rules. Query results should retain the matched tag ID, matching path, and vocabulary version so that cross-node results can be reproduced rather than returning only localized names.

12.2.3 Tag Recommendation and Discovery Use

During registration, recommendation results enter Resource Metadata only after confirmation by the resource provider. During discovery, the same tag ID, aliases, and hierarchical paths may be used for filtering or ranking. Recommendation hits, tag hits, and trusted-resource verification should be expressed separately in the response.

Resource description -> Recommended candidates -> Provider confirmation -> Written to ResourcePackage
                                                                         -> Discovery index
Query text -> Intent and alias parsing -> Tag conditions -> Candidate ranking

12.2.4 Tag Tree Version Management

When a tag tree is published, it should have a comparable version identifier and effective time. Tags from an older version may retain parsing mappings during a migration period, but the original resource declarations must not be silently rewritten. Until index rebuilding is complete, query results should identify the vocabulary version used.

12.3 Tag Hierarchies, Identifiers, Aliases, and Localization

A tag object should at least distinguish its normative identifier, display name, aliases, language, and version:

An unknown tag may be retained as ungoverned provider text, but it must not be presented as an official Root platform tag.

The responsibilities of tag IDs, display names, aliases, and hierarchical paths should remain separate. A query may first use a localized name or alias to find the normative ID and then use the normative ID for structured filtering; the returned result should retain both the actual resource declaration and the matched normative tag. This supports Chinese, English, and synonym queries without treating a display translation as a new capability declaration.

12.4 Tag Selection and Recommendation During Registration

12.4.1 Resource Provider Selection

The resource provider may accept, cancel, or modify recommended tags. The final submission should retain both the provider’s original description and the selected normative tags so that it remains possible to explain “what the resource declared” and “what the system recommended.”

12.4.2 Root Platform Recommendation

The Root platform or its governance materials provide the tag tree, aliases, and version. A recommender generates candidates according to the resource type, name, description, use case, and protocol. The recommender does not issue a resource control proof and does not replace registration validation.

12.4.3 Custom Tag Supplement

Custom tags express business terms that are not yet covered by the official vocabulary. A custom tag must carry a source or namespace and must be stored separately from official tags. It may participate in text retrieval, but it cannot directly change the resource type, authorization domain, or publication status.

12.4.4 Tag Validation and Persistence

Before saving, the system should at least validate the tag ID, vocabulary version, parent-node relationship, language, duplicates, and compatibility with the resource type. The validation result should be associated with the resource DID, resource version, and ResourcePackage digest. A recommendation failure or an expired tag must not cause a silent rewrite.

12.5 Custom Tags and Provider Descriptions

Custom tags are suitable for specific business terms, organization-specific names, or capabilities that have not yet entered the public vocabulary. They should be stored separately from official Root platform tags and should carry provider namespace or source information. Names, descriptions, use cases, and other free text should also retain the original text and language marker. An official tag ID must come from the currently available tag tree; a custom vocabulary must not be promoted to an official tag merely because its format or semantics appear similar.

A Discovery node may use custom tags and provider descriptions for lexical or semantic retrieval, but the result explanation must distinguish among “provider declaration,” “official tag hit,” and “retrieval-model inference.” Duplicate tags, excessively long text, invalid characters, tags that clearly conflict with the resource type, and keywords intended to manipulate ranking should be rejected, truncated, or degraded to ordinary text according to the node’s input validation and indexing strategy. The processing result should retain a traceable reason and must not overwrite the original submission.

12.6 Semantic Governance Change Process

Semantic governance changes should be expressed through new versioned materials rather than by directly rewriting old tags or historical resources. A change record should at least identify the change type, affected tag IDs, old and new versions, alias or hierarchy mappings, effective time, and the effects on registration recommendations and discovery indexes. Additions and renamings can usually be made compatible through new mappings; merges and splits require an explicit explanation of how old tags are queried; deprecated tags should stop being recommended for new resources while the original values and parseable relationships of historical resources are retained.

After a change is published, the registration recommender may load the new vocabulary, and the Discovery node may gradually rebuild related indexes by resource DID and resource version. Until rebuilding is complete, query results should be able to state the vocabulary or index version used. If an old tag cannot be mapped, the node may retain its original text for text retrieval, but must not present it as a definite hit of a new tag. Tag governance changes semantic interpretation and retrieval materials only; they do not change the resource DID, control relationship, registration credential, or Root platform publication fact.

12.7 Semantic Index Construction by Discovery Nodes

12.7.1 Index Inputs

The index inputs of a Discovery node fall into three categories:

1. Resource facts: resource DID, version, public DID Document, and Resource Metadata.
2. Semantic materials: normative tags, aliases, names, descriptions, use cases, protocols, and languages.
3. Governance materials: lifecycle, Root proof reference, authorization domain, tag tree version, and source node.

Private keys, unpublished drafts, and internal configuration must not enter the index.

12.7.2 Tag Index

The tag index should at least support filtering by normative tag ID, hierarchical path, language, and vocabulary version, and should retain the tag source. An index hit only means that the resource declaration or index record matches; the node must still check whether the resource is in a discoverable state.

12.7.3 Text and Semantic Indexes

The text index may cover names, descriptions, and use cases; the semantic index may use a recommender or an optional vector implementation. Both should return the matched fields, index version, and matching basis, and neither may add capabilities that the resource did not declare.

12.7.4 Index Update and Deletion

When the resource version, lifecycle, Root proof, or tag tree version changes, the node should perform an incremental update by resource DID and version. After a revocation, suspension, or deletion event arrives, the index may retain an audit record, but the resource must not continue to be returned as a normal discoverable candidate.

12.8 Matching Tags, Text, Protocols, and Resource Types

The four types of conditions have different roles in a query: resource type and an explicitly specified version are generally used to limit candidate categories; capability tags and protocols may serve as explicit filters; text in names, descriptions, and use cases is mainly used for relevance ranking. Multiple explicit conditions are generally processed as an intersection. A tag query requires a candidate to satisfy the requested tag set, while a protocol may match a protocol binding or service declaration. Semantic similarity may improve ranking, but it must not bring a candidate that fails a hard condition back into the result set.

Candidate eligibility = Visibility and lifecycle + Explicit structured conditions
Relevance ranking = Tag/protocol hits + Text relevance + Semantic similarity
Trust decision = DID Document + Credentials/Root proof + Caller policy

The first two lines define the discovery retrieval scope, while the last line is an independent pre-invocation check for identity, publication, and calling policy. When the semantic service is unavailable, a Discovery node may fall back to lexical or structured retrieval, but it must not relax the authorization domain, lifecycle, or explicit conditions.

12.9 Query Explanation and Matching Details

12.9.1 Query Intent Parsing

Query parsing should output auditable intermediate conditions, such as resource type, capability tags, protocol, language, and status filters. An uncertain term may be retained as a text condition and must not be forcibly converted into an official tag.

{
  "query": "I need a tool that can search code repositories and summarize project structures",
  "parsed": {
    "resourceType": "tool",
    "capabilities": ["code.repository.search", "code.structure.summarization"]
  }
}

12.9.2 Tag and Text Matching

Tag hits, alias hits, original-text hits, and semantic-inference hits should be returned in separate categories. When a hard filter is not satisfied, a relevance score must not cause the candidate to re-enter the result set.

12.9.3 Structured Condition Matching

Resource type, protocol, authorization domain, lifecycle, and publication status are structured conditions. The result for a structured condition should be explicitly expressed as satisfied, unsatisfied, or unknown; unknown must not be treated as satisfied.

12.9.4 Result Explanation

The query explanation interface of the current Discovery node accepts the same ResourceDiscoveryQuery as an ordinary discovery query, but returns dynamic JSON rather than ResourceDiscoveryResponse. The explanation may contain items, candidateCount, matched, various matching scores, tag overlap, structured-condition hits, and semantic-search status. These fields are observable retrieval results, not new resource proofs. A client should use the explanation to answer “why was this returned,” while relying on the candidate resource’s DID Document, ResourcePackage, Root proof, and governance status to answer “can this be trusted or invoked.”

An explanation should at least contain the resource DID, matched fields or tags, vocabulary/index version, and the source of trusted status. The distinction between the two types of information can be expressed as follows:

“Relevant” means that the query matches the resource description; “trusted” additionally requires independent verification of the DID, control proof, Root proof, authorization status, and lifecycle.

Query explanations should retain the observable path from natural language to structured conditions. For example, when the user enters “I need a tool that can search code repositories and summarize project structures,” the system may identify “tool” as a candidate resource type, and “search code repositories” and “summarize project structures” as capability or text-retrieval clues. If the current vocabulary has no reliable mapping to an official tag, the system should retain the original sentence and ordinary text hit rather than create a new tag based on model inference. The explanation may display matched tags, fields, aliases, and index version, but should not expose unnecessary internal model details.

12.10 Multilingual Semantic Discovery

12.10.1 Chinese and English Resource Descriptions

Chinese and English descriptions may be stored together, and the original text should carry a language marker. Translated or machine-generated text may serve as a retrieval projection only and must not replace the provider’s original description.

12.10.2 Multilingual Tags

Tag names in different languages should map to the same normative tag ID. If no reliable mapping exists, the name should be retained as ordinary text rather than used to create an ungoverned new synonym relationship.

12.10.3 Query Language Identification

Language identification selects only the lexical, alias, and tokenization paths. It must not change resource type, status, or trust-filter conditions. A mixed-language query should retain the parsing basis for each segment.

12.10.4 Cross-Language Matching

Cross-language hits should return the normative tag ID, the language and alias actually matched, and an indication of whether the hit came from tag mapping or text translation. A cross-language hit does not mean that the resource has an additional capability.

12.11 Extensibility for Vector and Hybrid Retrieval

The semantic extension of the current Discovery node may use PostgreSQL/pgvector and an HTTP embedding service to build resource-level semantic indexes; a local semantic recommender provides auxiliary recommendations for capability tags, resource types, and protocols. The choice of backend is a deployment and reference-implementation choice and must not change the processing rules for resource DID, ResourcePackage, authorization domain, lifecycle, or Root proof. A semantic index should also record the model name, model version, vector dimension, index version, and semantic-source hash so that results before and after rebuilding can be explained.

When the model, dimension, or semantic vocabulary changes incompatibly, the corresponding index should be rebuilt first, and the new results should then be served as a single index version to callers. An old index may be retained during migration, but scores produced by different models must not be compared directly.

12.12 Semantic Governance Compatibility and Migration

During migration, three types of information should be retained together: the original tags and descriptions submitted by the resource provider, the vocabulary version used at that time, and the parseable mapping in the new version. A compatibility mapping may allow old queries to continue finding a resource, but it must not rewrite the original fields in historical ResourcePackages. After a Discovery node completes index migration, it should update the index version. If migration is incomplete or a tag cannot be mapped, a result may continue to serve as limited text-based reference, but its semantic-governance status should be stated.

12.13 Semantic Vocabulary Versioning and Change Impact

Vocabulary versions and semantic index versions should be recorded separately: the former identifies the version of the tag tree and alias materials, while the latter identifies the inputs actually used by a particular Discovery node to construct its retrieval data. The effects of the two types of changes can be understood as follows:

When rolling back, the system should restore the previous verifiable vocabulary and index versions rather than deleting resource history. Query results and operational diagnostics should at least identify the vocabulary version, index version, and update time used, so that it is possible to explain why the same query produces different rankings on different nodes.

12.14 Semantic Governance Auditability

The audit records for semantic governance need to answer “who changed what in which vocabulary version and at what time, and which recommendations and indexes were affected.” At minimum, the records should associate the operator or governance subject, operation time, change type, old and new values, vocabulary version, reason, impact scope, index rebuilding status, and rollback basis. Audit records explain changes in semantic materials; a tag-change record must not be mistaken for a resource registration credential or resource control proof.

Registration recommendations and discovery queries should also retain necessary references. For example, a recommendation may be associated with an input digest, vocabulary version, and recommendation candidates; a discovery explanation may be associated with matched tag IDs, aliases or text fields, index version, and resource DID. Natural-language originals, caller information, and internal model outputs should follow the deployment operator’s access-control and minimum-retention policies. A public interface should expose only the minimum content needed for explanation.

12.15 Mapping Natural-Language Queries to Structured Conditions

Natural-language mapping should distinguish between conditions that can be assigned to structured fields and expressions that can only serve as retrieval clues. For example, “find a tool that can search code repositories and summarize project structures” may produce a candidate resource type, candidate capability tags, and text-retrieval terms. Words such as “latest,” “trusted,” and “invocable” may participate in deterministic filtering only when the protocol and governance materials provide corresponding fields or facts; otherwise, they can serve only as ranking or explanation hints. An uncertain term must retain its original text and must not be forcibly mapped to an official tag or authorization condition.

{
  "query": "I need a tool that can search code repositories and summarize project structures",
  "structuredConditions": {
    "resourceType": "tool_api",
    "capabilityTags": ["code.repository.search"]
  },
  "textTerms": ["summarize project structures"],
  "mappingStatus": "suggested"
}

The object above is an illustrative intermediate result for explanation and is not the fixed response format of the current discovery interface. A formal request must still use the discovery-query fields specified in Chapter 11. The value suggested indicates a semantic suggestion; the caller or resource provider must still confirm the tag, resource type, and protocol conditions. If mapping fails, the vocabulary version is incompatible, or the language does not match, the system may fall back to original-text retrieval or return an explicit result indicating that no usable mapping is available, but it must not conceal the failure as an incorrect formal condition.

References