Document schema

A noggin's serialized form — the YAML or JSON payload that providers read and write. The same JSON Schema validates both encodings because YAML 1.2 is a JSON superset.

The canonical machine-readable file lives at noggin.schema.json. The page below is generated from it on every build.

Use it in VS Code

Install the Red Hat YAML extension and add to your settings:

"yaml.schemas": {
  "https://dornstein.github.io/noggin/noggin.schema.json": [
    ".noggin.yaml",
    "**/.noggin/*.yaml"
  ]
}

Top-level shape

A noggin: a tree of work items with append-only notes, plus a cursor marking which item is currently active. YAML 1.2 is a JSON superset, so this schema validates both YAML and JSON renderings.

Field	Type	Description
`schemaVersion` (required)	`1` (const)	Version of the noggin data model represented by this document.
`active` (required)	`ItemKey` \| `null`	Opaque key of the item currently marked active, or null when no item is active. When non-null, must reference an item in `items`; referential integrity is not expressible in pure JSON Schema and is the responsibility of the producer.
`items` (required)	Array<`Item`>	Flat list of items. Tree structure is implied via `parentKey`. Sibling order is array order.

Definitions

`ItemKey`

Opaque, stable, never-reused item identifier. Treat as a string token; do not parse or assume a format.

Type: string

Min length: 1

`IsoTimestamp`

ISO-8601 / RFC 3339 date-time string.

Type: string

Format: date-time

`Note`

A single entry in an item's append-only note log.

Field	Type	Description
`timestamp` (required)	`IsoTimestamp` \| `null`	When the note was appended. May be null only for notes whose origin did not record a timestamp.
`text` (required)	`string`	Note body. Free-form text. The reserved text `closed` records the transition of the parent item from open to done.

`Item`

A single work item in the noggin tree.

Field	Type	Description
`key` (required)	`ItemKey`
`parentKey` (required)	`ItemKey` \| `null`	Opaque key of the parent item, or null for root items. Multiple roots are allowed. When non-null, must reference an item in `items` and must not introduce a cycle; referential integrity and acyclicity are the responsibility of the producer.
`title` (required)	`string`	One-line human label.
`done` (required)	`boolean`	False while the work is live, true once finished. The transition open→done is conventionally recorded by appending a note with text `closed`; the reverse transition does not modify notes.
`createdAt`	`IsoTimestamp`	When the item was created. Optional in the data model; producers are encouraged to set it.
`notes` (required)	Array<`Note`>	Append-only log of `{ timestamp, text }` entries.

Invariants beyond the schema

JSON Schema can describe shapes; it can't express referential integrity. The engine enforces these additional rules on every save:

Every item has a unique key.
Every non-null parentKey references an existing item.
active, if non-null, references an existing item.
Done items remain in the tree (they're not deleted) and can be reverted with edit --open.
A done item may have open descendants only when it was closed with --force. The standard close paths (done, pop, edit --done without flags, or with --close-all) preserve the stronger invariant "done items have no open descendants."

Example

schemaVersion: 1
active: i-20260616-184644-f04bf5
items:
  - key: i-20260616-184644-f04bf5
    parentKey: null
    title: ship the redesign
    done: false
    createdAt: '2026-06-16T18:46:44.071Z'
    notes:
      - timestamp: '2026-06-16T18:46:45.625Z'
        text: 'found the storage abstraction in tableStorageService'
  - key: i-20260616-185011-300abc
    parentKey: i-20260616-184644-f04bf5
    title: write the spec
    done: true
    createdAt: '2026-06-16T18:50:11.000Z'
    notes:
      - timestamp: '2026-06-16T18:50:11.300Z'
        text: closed