Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/dev/llms.txt
Full corpus: https://docs.registrystack.org/dev/llms-full.txt

# Document Store configuration reference

> Generated key-path reference for the Registry Document Store project and runtime files.

import ConfigurationFormatChecks from '../../../components/ConfigurationFormatChecks.astro';

import ConfigurationReference from '../../../components/ConfigurationReference.astro';
import reference from '../../../data/generated/documents-configuration.json';

The Registry Document Store reads two files: the `documents.yaml` project that declares access
profiles, document policies, and hooks, and the `runtime.yaml` an operator deploys.

## Contract status

| File | Kind | Status | Source |
| ---- | ---- | ------ | ------ |
| `documents.yaml` | `DocumentsProject` | Pre-1.0, may change | `products/documents/generated/project/project.schema.json` |
| `runtime.yaml` | `DocumentsRuntimeConfig` | Pre-1.0, may change | `products/documents/generated/runtime/runtime.schema.json` |

Every mapping is closed: an unknown key is refused with its path. JSON Schema is not the
acceptance path: a document these schemas accept still has to pass `documentsctl check`, which
resolves the access profiles each policy names and checks each profile's role against the
policy that uses it. The check also refuses:

- an OAuth client listed in `requesterClients` of two profiles
  (`documents.project.shared-requester-client`);
- a profile whose `principalClaim` differs from another profile's with the same `actorKind`
  (`documents.project.mixed-principal-claim`): every profile of one actor kind reads the subject
  from one claim;
- a hook whose `handler.destinationId` the runtime configuration does not bind under
  `destinations.hooks` (`documents.runtime.unbound-hook-destination`, at `/destinations/hooks`),
  when the check is given both `--project` and `--runtime-config`. The runtime refuses to start
  with the same diagnostic at the same position, before it connects to the database, and
  `documentsctl verification replay`, which activates the same hooks, refuses with it too.

A profile's `requesterClients`, `requiredScopes`, `actorKind`, and `principalClaim` are what an
access token must match, beside the runtime's `authentication.oidc` block.
[Access tokens](../../operate/documents/#access-tokens) lists every header and claim a token
must carry.

{/* Evidence: docs/site/scripts/generate-documents-configuration.mjs, CONTRACTS;
    crates/registry-documents-core/src/project.rs, DocumentsProject and reference_findings;
    crates/registry-documents/src/config.rs, DOCUMENTS_RUNTIME_KIND and project_findings;
    crates/registry-documents/src/runtime.rs, prepare_with and check_against_project;
    products/documents/RUNTIME-CONFIG.md. */}

## Key paths

A key path writes a property as `name`, an array item as `name[]`, and a map entry whose name you
choose as `name.*`, as in `documentPolicies.*.mandatoryRestrictions.cleanupGraceHours` or
`destinations.hooks.*.url`.

{/* Evidence: docs/site/scripts/configuration-reference.mjs, collectFields();
    docs/site/src/components/ConfigurationReference.astro. */}

{/* Generated from src/data/generated/documents-configuration.json, built from
    products/documents/generated/{project,runtime}/*.schema.json.
    Run npm run generate from docs/site. */}
<ConfigurationReference contracts={reference.contracts} prefix="documents" />

## Check commands

Both files have a command that checks them offline, with no service, database, or secret. Each
prints the diagnostics, JSON output, and exit codes that
[Check a file before you deploy it](../configuration-files/#check-a-file-before-you-deploy-it)
describes.

<ConfigurationFormatChecks product="documents" />

## Next

[Document Store API](../apis/registry-documents/)