Schema Types

Brainfile uses JSON Schema to define the structure of board configuration and task files.

Available Schemas

Schema	v2 URL	Purpose
Base	/v2/base.json	Shared fields (title, agent, rules)
Board	/v2/board.json	Board configuration (columns, types)
Task	/v2/task.json	Standalone task documents
Contract	/v2/contract.json	Task contract object (task.contract)
Epic	/v2/epic.json	Epic documents (groups related tasks)
ADR	/v2/adr.json	Architecture Decision Records

Extensible by design

These are the built-in types, but Brainfile is not limited to them. You can define your own schema types for any use case — bug, rfc, spike, incident, whatever fits your workflow. Just set type: your-type in the frontmatter and optionally point schema: to your own JSON Schema URL.

Board (Default)

Board configuration defines columns, document types, and project rules. Tasks are standalone files in .brainfile/board/.

---
type: board
schema: https://brainfile.md/v2/board.json
title: My Project
columns:
  - id: todo
    title: To Do
  - id: in-progress
    title: In Progress
types:
  epic:
    idPrefix: epic
    completable: false
---

Minimal Board

---
type: board
title: My Project
columns:
  - id: todo
    title: To Do
---

Only title and one column are required.

View Board Schema · Example

Task

Standalone task documents with YAML frontmatter and optional markdown body. Each task is an individual .md file in .brainfile/board/ (active) or .brainfile/logs/ (completed).

---
id: task-1
title: Implement feature
column: todo
priority: high
tags: [backend]
assignee: codex
parentId: epic-1
---

Minimal Task

---
id: task-1
title: Fix login bug
column: todo
---

Only id, title, and column are required.

View Task Schema · Docs

Contract (Task Extension)

Task contracts define structured deliverables, validation commands, and constraints for PM-to-agent workflows. Embedded in the contract field of a task file.

contract:
  status: ready
  deliverables:
    - type: file
      path: src/feature.ts
      description: Implementation
  validation:
    commands:
      - npm test

Minimal Contract

contract:
  status: ready

Only status is required — deliverables and validation are optional.

View Contract Schema · Docs

Parent-Child Relationships

Any document can be a parent or child of any other document using parentId. The parent tracks its children with a children array, and each child points back with parentId. This is not limited to epics — you can nest tasks under tasks, ADRs under epics, or any combination that fits your workflow.

# Parent: a regular task
---
id: task-10
title: Refactor auth module
column: in-progress
children: [task-11, task-12, task-13]
---

# Child: points back to parent
---
id: task-11
title: Extract token validation
column: todo
parentId: task-10
---

Epic

A common pattern for grouping related work. Epics extend the task schema with children and status fields, but any type can serve as a parent.

---
id: epic-1
type: epic
title: Authentication System
column: in-progress
children: [task-1, task-3, task-4]
status: active
---

Minimal Epic

---
id: epic-1
type: epic
title: Authentication System
column: todo
---

children and status are optional — add them as tasks are created.

View Epic Schema

ADR

Architecture Decision Records with lifecycle status and supersession tracking. Extends the task schema.

---
id: adr-1
type: adr
title: Use Postgres for user data
column: todo
status: proposed
---

Minimal ADR

---
id: adr-1
type: adr
title: Use Postgres for user data
column: todo
---

status defaults to proposed if omitted.

View ADR Schema

Base Schema

All brainfile config files inherit from the base schema which defines shared fields:

---
title: string           # Required
type: string            # Optional (defaults to board)
schema: string          # Optional JSON schema URL
protocolVersion: string # Optional version string
agent:
  instructions: []
  llmNotes: string
  tools: {}
rules:
  always: []
  never: []
  prefer: []
  context: []
---

Minimal Base

---
title: My Project
---

Only title is required — everything else has sensible defaults.

View Base Schema

Type Inference

When type is not specified, tools determine the type by:

1. Schema URL — /v2/board.json → board
2. Filename suffix — project.board.md → board
3. Structural analysis — columns[] present → board
4. Default → board

Schema Directories

Version	URL	Status
v2	brainfile.md/v2/	Current

Next Steps

• Protocol Specification — File format details
• API Reference — Library documentation
• Core Library — Build custom tools