# Registry directory

Registry operators run their own OSD registries. Clients need to know who these operators are and where to send searches.

The official list of participating registries is at `https://openservicedirectory.org/.well-known/osd-registries.json`. It identifies each registry, its operator, and its search endpoint.

The open-source OSD CLI is coming soon and will use this URL for registry discovery. The URL must serve JSON directly because the CLI rejects redirects.

Companies can run OSD registries without participating in this directory. Those registries are not listed here.

## Directory document

The registry directory JSON document contains three top-level fields:

| Field | Meaning |
| --- | --- |
| `schemaVersion` | The directory format version, `0.1.0`; independent of the OSD search contract |
| `updatedAt` | The directory revision's UTC timestamp in `YYYY-MM-DDTHH:mm:ssZ` form |
| `registries` | An array of registry records, which may be empty |

The directory uses format version `0.1.0` alongside the first OSD contract release, `0.3.0`. These versions identify different documents. Validate the directory with the [registry directory JSON Schema](/schemas/osd-directories/0.1.0.schema.json), using a Draft 2020-12 validator with format validation enabled, and reject unsupported directory versions. Unknown object properties are invalid.

Each content revision advances `updatedAt`.

## Registry records

Each record identifies one registry and contains these fields:

| Field | Meaning |
| --- | --- |
| `id` | Stable registry identifier, retained across name and endpoint changes and never reassigned |
| `name` | Nonempty human-readable registry name |
| `operator` | The provider responsible for the registry |
| `searchEndpoint` | The complete HTTPS URL to which search requests are posted |
| `status` | Participation status: `active` or `suspended` |

The `operator` object contains its own `id`, `name`, and `url`. These identify the provider and its public HTTPS website. Registry and operator IDs are lowercase ASCII slugs of at most 64 characters. Operator names are nonempty. URLs are absolute HTTPS URLs with a hostname and no user information or fragment.

Registry IDs and search endpoints are unique. Equivalent host casing and default HTTPS ports do not make an endpoint distinct. Repeated operator IDs must have identical operator records.

These uniqueness and operator-consistency checks are additional to JSON Schema validation. The website build applies both to the published directory.

The published directory is currently empty (`"registries": []`). This fictional
example shows the format of a registry entry:

```json
{
  "schemaVersion": "0.1.0",
  "updatedAt": "2026-10-05T02:02:34Z",
  "registries": [
    {
      "id": "example",
      "name": "Example OSD registry",
      "operator": {
        "id": "example",
        "name": "Example operator",
        "url": "https://operator.example"
      },
      "searchEndpoint": "https://registry.example/search",
      "status": "active"
    }
  ]
}
```

## Participation status

Each registry's `status` controls its participation in default discovery:

- `active`: included in default discovery.
- `suspended`: retained in the directory but excluded from default discovery.

A removed registry is absent from the document. Empty and fully suspended directories are valid.

## Search endpoints

Send `POST` requests to the complete `searchEndpoint` URL. Do not append `/search`. The endpoint already includes its path. The request and response follow the [registry search contract](/0.3.0/docs/reference/registry/), including exact contract-version negotiation. Directory membership does not change that contract.

The CLI's `--target` option takes a registry **base URL**, such as `https://registry.example`, and appends `search` itself. With neither `--target` nor `OSD_REGISTRY_URL` configured, the CLI searches the active registries in this directory. See the [CLI reference](/0.3.0/docs/reference/cli/).

## Brand endorsement

Participation in the directory does not endorse a registry's support agents or establish a brand's identity.

Identify the intended brand and compare each candidate with the brand's published entry. The [trust model](/0.3.0/docs/concepts/trust-model/) explains what a match establishes. Registry membership and search relevance do not replace that check.