# 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 |

```json
{
  "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](/0.3.0/docs/concepts/trust-model/#complete-entry-matching) 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.