OSD entry requirements

Open Service Directory (OSD) combines the pinned ARD v0.91 entry model with required brand identity terms and a brand-domain endorsement rule. It keeps ARD’s field names and meanings. Schemas define structural validity. Endorsement matching is a separate behavioral rule.

Required entry fields

Field	Requirement
identifier	Domain-anchored urn:air:<publisher>:<namespace>:<name>. The publisher segment anchors the agent’s discovery identity
displayName	Human-readable name
type	Media type of the artifact, such as an MCP Server Card. It names the document, not an operation
url or data	Exactly one. url references the artifact document, which is not necessarily the agent’s endpoint. data holds the complete artifact as a JSON object
@context	Object mapping osd to https://openservicedirectory.org/ns#
osd:brandName	The represented brand’s name
osd:brandDomain	The brand’s canonical domain, where its endorsement is published. The agent and card may be hosted elsewhere

{
  "identifier": "urn:air:airline.example:support:assistant",
  "displayName": "Example Air Support",
  "description": "Support for cancelled flights and rebooking.",
  "representativeQueries": ["My flight was cancelled", "Help me rebook my flight"],
  "type": "application/mcp-server-card+json",
  "url": "https://support.airline.example/server-card.json",
  "@context": { "osd": "https://openservicedirectory.org/ns#" },
  "osd:brandName": "Example Air",
  "osd:brandDomain": "airline.example"
}

This fictional entry validates against osd-catalog-entry/0.3.0.schema.json. Brand identity sits directly on the entry, not in metadata. A conforming ARD consumer supplies the ARD base context. The entry declares only the OSD namespace. Schema validation does not establish domain ownership or business identity.

Additional ARD terms

ARD defines fields such as description, representativeQueries, tags, capabilities, version, updatedAt, and metadata. Use them with the meanings defined by ARD. Values directly inside metadata must be strings, numbers, booleans, or null, not nested objects or arrays.

ARD recommends two to five representativeQueries. The schema does not enforce it. Optional fields that are present still take part in endorsement comparison.

capabilities is a discovery and filtering signal. The agent’s native protocol exposes its actual operations, and its authorization decides which the customer may use. Optional trust information follows ARD’s declared-framework model. Validation and matching do not verify signatures.

Brand-domain manifest

Publish entries at https://{osd:brandDomain}/.well-known/ard.json. The manifest requires an entries array whose members meet the OSD entry requirements. Additional top-level properties are permitted.

Each entry independently endorses the agent it describes. Endorsing a card hosted on another domain does not endorse anything else from that host or registry.

Complete structural comparison

To check a registry candidate, compare its complete entry with an entry in the manifest retrieved from the intended brand’s domain:

• Exclude search annotations such as score and source. Include every other field, including optional fields, extensions, and nested values.
• Objects compare regardless of property order or JSON whitespace.
• Strings and URLs match exactly, without normalization or fuzzy repair.
• Arrays are unordered sets unless their owning specification gives order meaning. Duplicate members in an unordered array are invalid.
• For a url entry, the published reference is compared. The fetched artifact and the agent’s behavior are not. Inline data is compared.

A missing field or different value is a mismatch. An unavailable or invalid manifest is inconclusive. JSON Schema alone does not enforce these rules. See the trust model for what each outcome means.

Registry result requirements

Every OSD search result has a complete OSD entry, an integer score from 0 to 100 expressing semantic relevance, and a URI source identifying the registry endpoint where the entry was indexed. The registry must preserve the published entry, including optional fields, or matching fails. The response schema checks fields and types. Only the comparison above shows the registry returned the entry unchanged.