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

# formation.policy/v0.2

Frontmatter fields of a `formation` document. Every security-, cost- and execution-relevant
value is a typed field; prose in the body can explain a rule but never override it. Undeclared
fields are rejected.

## Fields

- `schema` (required): exactly `formation.policy/v0.2`
- `kind` (required): exactly `formation`
- `created_at` (optional): ISO 8601 UTC timestamp, pattern `^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$`, at most 30 characters
- `visibility` (optional): one of `private`, `public`
- `name` (required): artifact name, pattern `^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$`, at most 64 characters
- `version` (required): semantic version, pattern `^(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$`, at most 64 characters
- `topology` (required): one of `single`, `reviewer`, `adaptive_review`, `custom`
- `patterns` (optional): array of 0 to 23 items, each one of `single_agent`, `fan_out`, `map_reduce`, `independent_workers`, `lane_swarm`, `supervisor`, `planner_worker`, `role_pipeline`, `hierarchical_delegation`, `blackboard`, `shared_ledger`, `mailbox_network`, `implement_review`, `critic_loop`, `council`, `debate`, `dynamic_spawning`, `coordinator_election`, `adaptive_routing`, `tree_search`, `architecture_search`, `successor_handoff`, `signed_coordination`
- `task_classes` (required): array of 1 to 16 items, each task class, pattern `^[a-z][a-z0-9_]{0,31}(?:\.[a-z][a-z0-9_]{0,31}){1,3}$`, at most 128 characters
- `capabilities` (required): array of 0 to 32 items, each identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `roles` (required): array of 1 to 16 items, each map (fields listed below)
- `roles[].id` (required): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `roles[].instructions_section` (required): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `roles[].model_slot` (required): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `roles[].allowed_tools` (required): array of 0 to 32 items, each tool identifier, pattern `^[a-z][a-z0-9_]{0,31}\.[a-z][a-z0-9_]{0,31}$`, at most 64 characters
- `handoffs` (required): array of 0 to 32 items, each map (fields listed below)
- `handoffs[].from` (required): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `handoffs[].to` (required): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `handoffs[].when` (required): map (fields listed below)
- `handoffs[].when.signal` (required): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `handoffs[].when.equals` (required): boolean
- `handoffs[].max_activations` (required): integer from 1 to 100
- `limits` (required): map (fields listed below)
- `limits.max_active_agents` (required): integer from 1 to 64
- `limits.max_role_invocations` (required): integer from 1 to 10000
- `limits.max_model_calls` (required): integer from 1 to 100000
- `limits.max_wall_time_seconds` (required): integer from 1 to 86400
- `limits.max_billable_tokens` (required): integer from 0 to 1000000000000
- `limits.max_episode_cost_usd_micros` (optional): integer from 0 to 1000000000000000
- `stop_conditions` (required): array of 1 to 5 items, each one of `accepted_by_external_validator`, `invocation_limit_reached`, `budget_limit_reached`, `wall_time_limit_reached`, `lease_lost`
- `dependencies` (required): array of 0 to 32 items, each map (fields listed below)
- `dependencies[].name` (required): artifact name, pattern `^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$`, at most 64 characters
- `dependencies[].digest` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `dependencies[].origin` (required): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `topology_id` (optional): identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `topology_version` (optional): semantic version, pattern `^(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$`, at most 64 characters
- `vocabulary_refs` (optional): array of 0 to 32 items, each map (fields listed below)
- `vocabulary_refs[].namespace` (required): vocabulary namespace, pattern `^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$`, at most 96 characters
- `vocabulary_refs[].id` (required): vocabulary identifier, pattern `^[a-z][a-z0-9_-]{0,63}$`, at most 64 characters
- `vocabulary_refs[].version` (required): semantic version, pattern `^(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$`, at most 64 characters
- `extensions` (optional): map of at most 16 entries, each map (fields listed below)