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

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

```json
{
  "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](https://agenticresourcediscovery.org/spec/#531-the-query-model):

- `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](https://agenticresourcediscovery.org/spec/#54-federation):

| 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`:

```json
{
  "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.