Registry

An Open Service Directory (OSD) registry indexes support entries and exposes ARD search. It owns its admission process and ranking. The public contract defines only the data exchanged with clients, not any operator’s administration API.

Search request

Send POST /search to the registry’s base URL with a JSON body and an exact OSD-Accept-Contract-Version:

POST /search HTTP/1.1
Host: registry.example
Content-Type: application/json
OSD-Accept-Contract-Version: 0.3.0

{
  "query": {
    "text": "cancelled flight rebooking",
    "@context": { "osd": "https://openservicedirectory.org/ns#" },
    "filter": {
      "osd:brandDomain": "airline.example",
      "type": "application/mcp-server-card+json"
    }
  },
  "federation": "none",
  "pageSize": 5
}

These are inherited ARD query semantics:

• query.text is required. Filters add structured constraints. They do not replace the text.
• Bind namespaced filter terms through the query’s @context.
• Values within one filter key are alternatives. Different keys apply together. A scalar is treated as a one-element array.
• Supported extension paths depend on the registry. An unsupported path can be rejected with 400 INVALID_ARGUMENT.

Results and pagination

The response requires a results array. Each member contains a complete OSD entry and these fields:

Field	Meaning
score	Integer from 0 to 100 measuring query relevance, not safety or endorsement
source	The registry where the entry was indexed

Registries must preserve every entry field, including optional fields, so clients can compare the copy with the brand’s publication.

Optional referrals point to other registries, and an optional pageToken fetches the next page. An empty results array can still come with referrals.

ARD’s default page size is 10 and its maximum is 100. Page tokens are opaque: pass them back unchanged, never parse or construct them.

Federation

The federation mode follows ARD’s federation rules:

Mode	Behavior
auto (default)	The registry queries upstream sources and returns combined results
referrals	The registry returns references to other registries for the client to consider
none	Only the queried registry’s index is searched

Following a referral is the caller’s decision. A referred registry’s listings are not automatically trusted and still need the brand-domain check.

Exact contract versions

A successful response declares the selected OSD-Contract-Version, sends Vary: OSD-Accept-Contract-Version, and links to the contract release manifest. Without a request header, the registry may use its configured default. With one, it must honor it exactly. An unsupported version returns 406 Not Acceptable with UNSUPPORTED_CONTRACT_VERSION, never a silent fallback.

Errors

The error body has errorCode and message:

{
  "errorCode": "INVALID_ARGUMENT",
  "message": "The requested filter path is not supported."
}

ARD defines standard classifications for invalid requests, missing authentication, missing resources, rate limits, and internal failures. OSD adds the unsupported-contract-version error. The schema validates the body shape only. It does not enumerate codes or bind them to HTTP statuses.

Admission and maintenance

Each registry defines its admission and maintenance process, which may include domain and publication checks, and should document what it checks. Admission does not establish a business’s legitimacy, reputation, or service quality, and it never replaces the client’s comparison with the brand’s published entry.

OSD does not standardize a submission, update, or removal API, an approval database, or a ranking algorithm. Operators document these separately.