Schema Reference

The canonical schema is context-yaml.schema.json, a JSON Schema draft 2020-12 document embedded in the binary and validated at parse time. This page documents all fields.

Top-level structure

CONTEXT.yaml structure

ktext: "1.0.0"       # required — schema version
identity: ...        # required
constraints: []      # optional
decisions: []        # optional
conventions: []      # optional
risks: []            # optional
dependencies: []     # optional
working: {}          # optional
ownership: {}        # optional
links: {}            # optional
x: {}                # optional — extension fields

identity

Required. Describes what the project is.

Field	Type	Required	Description
name	string	yes	Short project name
url	string	yes	Canonical repository URL
type	string	no	service, library, tool, cli, app, infra, monorepo, other
status	string	no	active, deprecated, experimental, archived
purpose	string	no	What this does and why it exists (scored for specificity)

example

identity:
  name: my-service
  url: https://github.com/org/my-service
  type: service
  status: active
  purpose: Handles payment processing for the checkout flow.

constraints

Hard rules that must never be violated. Constraints with specific, actionable language score significantly higher than vague ones.

Field	Type	Required	Description
content	string	yes	The constraint. Use must, never, always, prohibit, etc.
why	string	no	Reason — compliance, architecture, safety, etc.
scope	string	no	Where this applies (e.g. a package, layer, or environment)

example

constraints:
  - content: Never log raw card data or PII in any request handler
    why: PCI compliance
  - content: Always validate input at the service boundary before passing to domain logic
    why: Defense in depth — handlers must not trust callers

decisions

Architectural and technology decisions with their rationale. A decision without rationale is just a fact — the why is what matters.

Field	Type	Required	Description
title	string	yes	Short description of the decision
rationale	string	yes	Why this decision was made — scored for depth
status	string	no	accepted, superseded, deprecated, proposed
date	string	no	When the decision was made (YYYY-MM or YYYY-MM-DD)
reference	string	no	Link to an ADR, RFC, or discussion

example

decisions:
  - title: Use PostgreSQL for all persistent state
    rationale: Need transactional integrity and JSONB support for flexible metadata. Evaluated MySQL — lacks native JSONB and advisory locks.
    status: accepted
    date: "2024-03"

conventions

Coding and process rules that apply throughout the codebase.

Field	Type	Required	Description
rule	string	yes	The convention — scored for action verbs (use, write, run, call, etc.)
why	string	no	Why this rule exists
scope	string	no	Where this applies
reference	string	no	Link to documentation or style guide

example

conventions:
  - rule: Run all database queries through the repository layer — no raw SQL in handlers
    why: Keeps the domain layer testable and the persistence layer swappable
  - rule: Use structured logging (slog) with a request-scoped logger — never use fmt.Println

risks

Known fragile areas, tech debt, and operational concerns. High-severity risks without a mitigation are penalized.

Field	Type	Required	Description
content	string	yes	Description of the risk
severity	string	yes	high, medium, or low
mitigation	string	no	What you're doing about it — required for high severity to avoid a score penalty

example

risks:
  - content: Migration rollback untested beyond 2 schema versions
    severity: high
    mitigation: Add rollback smoke test to CI before the next release cycle

dependencies

External systems and libraries this project relies on. Including a why is strongly recommended — it distinguishes a meaningful dependency from a transitive one.

Field	Type	Required	Description
name	string	yes	Dependency name
url	string	yes	Documentation or homepage URL
why	string	no	What this project uses it for

example

dependencies:
  - name: PostgreSQL
    url: https://www.postgresql.org
    why: Primary data store — transactional integrity and JSONB for metadata
  - name: Redis
    url: https://redis.io
    why: Session cache and rate-limit counters

working

Developer environment information — build commands, directory layout, and operational notes.

Field	Type	Description
commands	array	Runnable commands with descriptions (build, test, lint, etc.)
structure	array	Key directories with descriptions
notes	string[]	Gotchas, setup steps, and workflow tips

example

working:
  commands:
    - command: make build
      description: build the service binary
    - command: make test
      description: run unit and integration tests
    - command: make migrate
      description: apply pending database migrations
  structure:
    - path: internal/payments/
      description: payment processing logic and provider integrations
    - path: internal/repository/
      description: all database access — no SQL outside this package
  notes:
    - Run migrations before starting the server locally
    - Set STRIPE_WEBHOOK_SECRET in .env.local for webhook testing

ownership

Field	Type	Description
team	string	Team or group name
escalation	string	Where to raise issues — Slack channel, PagerDuty, GitHub issues
maintainers	array	Named individuals with optional role

example

ownership:
  team: platform
  escalation: https://github.com/org/my-service/issues
  maintainers:
    - name: alice
      role: lead
    - name: bob

links

An open map of name → URL. No fixed keys — add whatever is useful.

example

links:
  repository: https://github.com/org/my-service
  issues: https://github.com/org/my-service/issues
  runbook: https://notion.so/...
  dashboard: https://grafana.internal/d/my-service

Extension fields

The x key is reserved for extension fields. Values here are not validated by the schema and do not affect scoring. Use them to add project-specific metadata without breaking validation.

example

x:
  oncall-rotation: https://pagerduty.com/...
  sla: 99.9%