Schema Reference Overview

PlanSpec uses JSON Schema to define the structure of plans, goals, and gates.

Document Structure

All PlanSpec documents follow a common structure:

yaml

apiVersion: planspec.io/v1alpha1
kind: Goal | Plan | Gate
metadata:
  name: string
  namespace: string        # Required
  labels: object           # Optional
  annotations: object      # Optional
spec:
  # Kind-specific fields

API Version

The current API version is planspec.io/v1alpha1.

The v1alpha1 designation indicates the schema is in active development. Breaking changes may occur before v1 release.

Kinds

PlanSpec defines three resource kinds:

Goal

Represents a desired outcome.

yaml

apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: my-goal
  namespace: default
spec:
  description: string
  acceptanceCriteria:
    - description: string
      id: string           # Optional

Plan

A set of tasks to achieve a goal.

yaml

apiVersion: planspec.io/v1alpha1
kind: Plan
metadata:
  name: my-plan
  namespace: default
spec:
  description: string
  goalRef:
    name: string
  graph:
    nodes:
      - id: string
        kind: Task
        description: string
        dependsOn: string[]  # Optional

Gate

A checkpoint requiring approval.

yaml

apiVersion: planspec.io/v1alpha1
kind: Gate
metadata:
  name: my-gate
  namespace: default
spec:
  gateType: approval | review | sign-off
  targetRef:
    kind: Execution
    name: string
  description: string        # Optional
  reviewers: string[]        # Optional

Metadata

All resources include metadata:

Field	Type	Required	Description
`name`	string	Yes	Unique identifier
`namespace`	string	Yes	Resource namespace
`labels`	object	No	Key-value pairs for organization
`annotations`	object	No	Arbitrary metadata

Labels

Labels are used for filtering and organization:

yaml

metadata:
  name: auth-plan
  namespace: default
  labels:
    team: backend
    priority: high
    sprint: "2024-Q1"

Annotations

Annotations store additional information:

yaml

metadata:
  name: auth-plan
  namespace: default
  annotations:
    planspec.io/created-by: "alice@example.com"
    planspec.io/source: "jira:PROJ-123"

Multi-Document Files

A single YAML file can contain multiple resources separated by ---:

yaml

apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: my-goal
  namespace: default
spec:
  description: The goal
  acceptanceCriteria:
    - description: Goal is achieved
---
apiVersion: planspec.io/v1alpha1
kind: Plan
metadata:
  name: my-plan
  namespace: default
spec:
  description: Plan to achieve the goal
  goalRef:
    name: my-goal
  graph:
    nodes:
      - id: implement
        kind: Task
        description: Implement the goal

Validation

Validate documents with the CLI:

bash

planspec validate --strict document.yaml

Or use the Playground for interactive validation.

Next Steps

Explore individual schema definitions:

Goal - High-level objectives with acceptance criteria
Plan - DAG of tasks with dependencies
Gate - Approval checkpoints
Execution - Runtime state tracking
Binding - Capability resolution rules
Capability - Reusable agent abilities

Or get started:

Quick Start - Try PlanSpec