---
schema: formation.doc/v0.1
kind: doc
visibility: public
canonical_url: https://topologyindex.com/docs/schemas/doc/v0.1.md
document_kind: doc
document_schema: formation.doc/v0.1
path: /docs/schemas/doc/v0.1.md
product_api_version: v1
schema_version: v0.1
title: formation.doc/v0.1
---

# formation.doc/v0.1

Frontmatter fields of a `doc` page. This service publishes these pages and never
accepts one, so the schema is a promise about what it serves: its tests check every page
against it. Prose in the body explains; the frontmatter is what to read.

## Fields

- `schema` (required): exactly `formation.doc/v0.1`
- `kind` (required): exactly `doc`
- `visibility` (required): exactly `public`
- `path` (required): resource path, pattern `^\/[A-Za-z0-9._~/-]{0,255}$`, at most 256 characters
- `canonical_url` (required): https URL, pattern `^https:\/\/[A-Za-z0-9.-]+(?:\/\S*)?$`, at most 512 characters
- `product_api_version` (required): API version, pattern `^v\d{1,4}$`, at most 5 characters
- `schema_version` (required): schema version, pattern `^v\d{1,4}\.\d{1,4}$`, at most 11 characters
- `title` (required): title, pattern `^[^\p{Cc}]+$`, at most 200 characters
- `description` (optional): description, pattern `^[^\p{Cc}]+$`, at most 400 characters
- `location` (optional): resource path, pattern `^\/[A-Za-z0-9._~/-]{0,255}$`, at most 256 characters. On a redirect only: where the resource is served.
- `schemas` (optional): array of 0 to 64 items, each map (fields listed below). On the contract directory: every published schema reference.
- `schemas[].kind` (required): one of `formation`, `execution_lock`, `workload_profile`, `suite`, `evaluation_plan`, `job_status`, `run`, `evidence`, `decision`, `adoption`, `subscription`, `error`, `service`, `account_status`, `recommendation_request`, `evaluation_plan_request`, `comparison_request`, `use_receipt`, `pattern_index`, `pattern`, `pattern_findings`, `domain_index`, `domain`, `domain_findings`, `guide`, `research_index`, `research`, `starter_index`, `doc`
- `schemas[].schema` (required): schema identifier, pattern `^formation\.[a-z][a-z0-9_]{0,63}\/v\d{1,4}\.\d{1,4}$`, at most 96 characters
- `schemas[].path` (required): resource path, pattern `^\/[A-Za-z0-9._~/-]{0,255}$`, at most 256 characters
- `guides` (optional): array of 0 to 32 items, each map (fields listed below). On the contract directory: every API guide.
- `guides[].title` (required): title, pattern `^[^\p{Cc}]+$`, at most 200 characters
- `guides[].path` (required): resource path, pattern `^\/[A-Za-z0-9._~/-]{0,255}$`, at most 256 characters
- `document_kind` (optional): one of `formation`, `execution_lock`, `workload_profile`, `suite`, `evaluation_plan`, `job_status`, `run`, `evidence`, `decision`, `adoption`, `subscription`, `error`, `service`, `account_status`, `recommendation_request`, `evaluation_plan_request`, `comparison_request`, `use_receipt`, `pattern_index`, `pattern`, `pattern_findings`, `domain_index`, `domain`, `domain_findings`, `guide`, `research_index`, `research`, `starter_index`, `doc`. On a schema reference: the kind it describes.
- `document_schema` (optional): schema identifier, pattern `^formation\.[a-z][a-z0-9_]{0,63}\/v\d{1,4}\.\d{1,4}$`, at most 96 characters
- `max_document_bytes` (optional): integer from 1 to 16777216. On a schema reference of a submitted kind: its size limit.
- `scheme` (optional): exactly `bearer`
- `credential_prefix` (optional): prefix, pattern `^[a-z]{1,8}_$`, at most 9 characters
- `scopes` (optional): array of 0 to 12 items, each one of `artifacts:read`, `formations:write`, `recommendations:read`, `evaluations:plan`, `evaluations:start`, `evaluations:read`, `evaluations:cancel`, `runs:report`, `adoptions:write`, `subscriptions:write`, `events:read`, `account:read`
- `tenant_prefix` (optional): path template, pattern `^[^\p{Cc}]+$`, at most 128 characters
- `routes` (optional): array of 0 to 128 items, each map (fields listed below)
- `routes[].method` (required): one of `GET`, `POST`
- `routes[].path` (required): path template, pattern `^[^\p{Cc}]+$`, at most 128 characters
- `routes[].access` (required): access, pattern `^[^\p{Cc}]+$`, at most 64 characters
- `errors` (optional): array of 0 to 17 items, each map (fields listed below)
- `errors[].code` (required): one of `malformed_syntax`, `invalid_credentials`, `insufficient_scope`, `plan_required`, `owner_approval_required`, `not_found`, `not_acceptable`, `conflict`, `idempotency_conflict`, `payload_too_large`, `unsupported_media_type`, `validation_failed`, `unsupported_version`, `unsupported_capability`, `quota_exceeded`, `internal_error`, `service_unavailable`
- `errors[].http_status` (required): integer from 400 to 599
- `max_frontmatter_bytes` (optional): integer from 1 to 16777216
- `max_yaml_nesting_depth` (optional): integer from 1 to 256
- `max_index_items` (optional): integer from 1 to 100000
- `document_byte_limits` (optional): map of at most 18 entries, each integer from 1 to 16777216
- `rollout` (optional): exactly `limited`
- `ticket_header` (optional): header name, pattern `^[A-Za-z-]+$`, at most 64 characters
- `receipt_schema` (optional): schema identifier, pattern `^formation\.[a-z][a-z0-9_]{0,63}\/v\d{1,4}\.\d{1,4}$`, at most 96 characters
- `receipt_route` (optional): route, pattern `^[^\p{Cc}]+$`, at most 64 characters
- `mcp_tool` (optional): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `ranking_kind` (optional): exactly `community_reported`
- `qualifies_as_evidence` (optional): boolean
- `used_by_recommendations` (optional): boolean