Core Concepts
OAN is easier to understand when its vocabulary is kept small and precise. The network is not held together by one endpoint, one database table, one search index, or one certificate. It is held together by a set of objects and roles that each carry a limited responsibility: identity, onboarding, acceptance, distribution, discovery, and verification.
This section introduces that vocabulary before the later sections walk through flows and code. The goal is not to make every reader memorize protocol fields. The goal is to make the important boundaries visible. A resource is not the same thing as a node. A Discovery result is not the same thing as Root acceptance. A capability tag is not an authorization domain. A DID Document is not the whole trust model. These distinctions are what keep OAN useful when many parties publish resources through many operators.
Concepts as Boundaries
OAN’s core concepts answer four recurring questions.
| Question | OAN concept | Why it matters |
|---|---|---|
| What is being published? | Trusted resource | OAN publishes agent-facing resources, not only agent profiles. |
| Who or what is the subject? | did:oan identity |
A stable identifier survives endpoint, version, and metadata changes. |
| Who is allowed to onboard or expose it? | Registrar, Root, Discovery | Infrastructure authority is separated and governed. |
| What exactly was accepted? | ResourcePackage and Root proof | Consumers can verify hashes, version, metadata, and acceptance. |
| Where is it allowed to operate? | authorizedDomains |
Domain scope is enforced as authorization, not treated as search text. |
| What can it do? | capabilityTags |
Capability hints help discovery without granting permission. |
These concepts intentionally do not collapse into one “resource record.” OAN is designed for a world where a Skill might be stored in a Git repository, an MCP server might run behind a service endpoint, an Agent Service might speak its own protocol, and a Tool/API resource might be described by an OpenAPI file or another schema. OAN provides the common trust envelope around those forms.
The Minimum Mental Model
A resource starts with identity and metadata. The identity is expressed through did:oan; the metadata describes resource type, services, bindings, capabilities, authorized domains, and package references. The resource is submitted through a Registrar. Root checks the submission, including Registrar authority and resource consistency, then accepts a version and creates verifiable publication evidence. Discovery nodes synchronize accepted packages, index their searchable surface, and return signed candidates. A client verifies the evidence before using the resource through its native protocol.
That is the whole path in one paragraph, but each noun in it matters. Registrar is not a general marketplace review board. Root is not a business-traffic gateway. Discovery is not a source of unchecked truth. The DID Document is not a runtime health guarantee. Capability tags are not permissions. Authorized domains are not marketing categories. ResourcePackage is not just a blob of metadata; it is the versioned unit that ties identity, hashes, lifecycle, and proof together.
Why OAN Uses Resource Vocabulary
Many agent ecosystems begin with “agents” as the main object. OAN uses “resource” because the ecosystem already contains useful things that are not full autonomous agents. A developer may publish a skill package that another assistant can install. A team may publish an MCP server exposing tools and prompts. A SaaS provider may expose a Tool/API endpoint suitable for agent workflows. A company may run an Agent Service with a business-specific invocation protocol.
If OAN only modeled agents, each of those forms would need to pretend to be the same kind of thing. The resource model avoids that. It lets each resource keep its native protocol while sharing identity, registration, discovery, and verification.
Trust Is Layered
OAN’s vocabulary reflects a layered trust design:
| Layer | Primary object | Typical check |
|---|---|---|
| Identity | DID and DID Document | Does the subject have stable keys and services? |
| Onboarding | Registrar submission | Was the submission made through an authorized Registrar? |
| Acceptance | Root proof | Did Root accept this version and these hashes? |
| Distribution | CDN package material | Do downloaded bytes match Root-accepted package facts? |
| Discovery | Signed Discovery response | Did an authorized Discovery node return this candidate? |
| Use | Native protocol invocation | Is the endpoint or artifact still bound to the verified identity? |
Layering is what makes OAN different from a directory or a search feature. A consumer can inspect evidence at several points and decide which checks to automate. An SDK can turn those checks into reusable code. An operator can monitor where a failure occurs: Registrar admission, Root acceptance, package publication, Discovery synchronization, or client-side verification.
Vocabulary As A Safety Mechanism
The vocabulary is not cosmetic. It prevents dangerous shortcuts. If a team calls capability tags “domains,” it may accidentally let search metadata influence authorization. If a UI calls Registrar acceptance “publication,” users may think a resource is Root-accepted before it is. If a gateway calls endpoint reachability “verification,” clients may skip package proof. Precise words protect precise behavior.
This is why OAN Docs repeat some distinctions across pages. Repetition is deliberate when the distinction is a security boundary. A strong ecosystem needs everyone to use the same terms for identity, scope, proof, lifecycle, and invocation.
What Implementers Should Preserve
Implementers can evolve APIs, storage engines, ranking algorithms, and deployment patterns, but they should preserve the concept boundaries. A future semantic Discovery engine may use better retrieval. A future Registrar may use richer validation. A future SDK may automate more checks. None of those improvements should collapse authorization domains into tags, Root proof into a status string, or DID identity into endpoint naming.
If a new feature makes one concept look like another, it needs careful design review.
What To Read Next
Read Trusted Resource first if you want to understand what OAN publishes. Read did:oan Identity if you care about identifiers, DID Documents, and stable resource naming. Read Registrar, Root, and Discovery if you want the node-role model. Read ResourcePackage and Root Proof if you want the evidence object that Discovery and SDKs rely on. Read Authorized Domains and Capability Tags together; their separation is a key part of the current implementation and prevents search metadata from being mistaken for governance scope.
For a deeper technical treatment, the OAN yellow paper gives the protocol architecture, while the did:oan DID Method Specification defines the public identity surface.