OpenJudgment Specification

Version: 0.1.0

Introduction

OpenJudgment is an open specification for recording human judgment moments in AI-assisted workflows. It defines a portable, tool-agnostic schema for capturing the pushbacks, corrections, directions, and preferences that developers exercise when working with AI coding assistants.

OpenJudgment standardizes how human steering in AI sessions is recorded — so that judgment can be captured, stored, and shared in a common format regardless of which AI assistant or tooling produced it.

Concepts

Steering

The act of a human guiding an AI assistant during a workflow: rejecting a suggestion, correcting a misunderstanding, asserting a preference, or redirecting an approach.

Episode

A discrete unit of work. One episode corresponds to one task or goal. It contains one or more moments and optionally records its outcome.

Moment

A single instance of human steering within an episode: a pushback, correction, direction, scope change, or preference assertion.

Judgment

The distilled record of a steering decision. Written in third person, it captures what was decided and why — without quoting the human directly.

Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

An OpenJudgment document MAY be serialized as JSON, YAML, or Markdown as defined in the Serialization section.

Serialization

JSON

The canonical serialization. The schema defined in this specification is expressed in JSON. All other serializations MUST be semantically equivalent to their JSON representation.

YAML

Tools MAY accept YAML as an alternative serialization.

Markdown

Tools MAY produce or consume a Markdown representation. The Markdown representation MUST be losslessly convertible to and from JSON.

The mapping is as follows:

YAML frontmatter maps to openjudgment; when tool or models are present in the document, they MUST appear in the frontmatter
Episode topic maps to a level-1 heading
Each moment maps to a level-2 heading with {timestamp} {type}, where {timestamp} is the verbatim ISO 8601 value of the moment's timestamp field; followed by ### Judgment, and ### Context MUST be included when context is present
Episode result maps to **Result**: {result} at the end of the file; when result is absent, this line MUST be omitted

Schema

This specification uses JSON Schema 2020-12 for all schema definitions.

Episode Object

The Episode Object is the root object of each OpenJudgment document. One file per episode.

Field	Type	Required	Description
`openjudgment`	`string`	yes	Spec version. MUST be `"0.1.0"`.
`topic`	`string`	yes	Short human-readable title for the task.
`tool`	`string`	no	The AI assistant used during the episode (e.g. `claude-code`, `cursor`).
`models`	`string[]`	no	The AI models used during the episode (e.g. `claude-sonnet-4-6`).
`moments`	Moment[]	yes	List of steering moments in ascending timestamp order. MUST have at least one.
`result`	`string`	no	Outcome: `completed`, `paused`, `cancelled`, or `failed`. Absence indicates the episode has no recorded outcome (e.g. still in progress).

Moment Object

A single instance of human steering within an episode.

Field	Type	Required	Description
`timestamp`	`string`	yes	ISO 8601 date-time of the steering message.
`type`	`string`	yes	One of: `pushback`, `direction`, `correction`, `scope-change`, `preference`.
`judgment`	`string`	yes	Third-person summary of what was decided and why. MUST NOT contain direct quotes from the human.
`context`	`string`	no	What the AI was doing at the moment of steering.

Moment Types

Type	Description
`pushback`	Developer rejects or overrides an AI suggestion.
`direction`	Developer gives explicit instruction on approach.
`correction`	AI misunderstood; developer clarifies.
`scope-change`	Developer narrows or shifts the goal.
`preference`	Developer asserts a way of doing things.

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openjudgment.org/schema/v0.1.0",
  "title": "OpenJudgment",
  "description": "An open schema for recording human judgment moments in AI-assisted workflows.",
  "type": "object",
  "required": ["openjudgment", "topic", "moments"],
  "additionalProperties": false,
  "properties": {
    "openjudgment": {
      "type": "string",
      "description": "The OpenJudgment spec version this document conforms to.",
      "const": "0.1.0"
    },
    "topic": {
      "type": "string",
      "description": "Short human-readable title for the task."
    },
    "tool": {
      "type": "string",
      "description": "The AI assistant used during the episode (e.g. 'claude-code', 'cursor')."
    },
    "models": {
      "type": "array",
      "description": "The AI models used during the episode (e.g. 'claude-sonnet-4-6').",
      "items": { "type": "string" }
    },
    "moments": {
      "type": "array",
      "description": "Ordered list of steering moments.",
      "minItems": 1,
      "items": { "$ref": "#/$defs/Moment" }
    },
    "result": {
      "type": "string",
      "description": "Outcome of the episode.",
      "enum": ["completed", "paused", "cancelled", "failed"]
    }
  },
  "$defs": {
    "Moment": {
      "type": "object",
      "required": ["timestamp", "type", "judgment"],
      "additionalProperties": false,
      "properties": {
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 date-time of the steering message."
        },
        "type": {
          "type": "string",
          "description": "The type of steering moment.",
          "enum": ["pushback", "direction", "correction", "scope-change", "preference"]
        },
        "judgment": {
          "type": "string",
          "description": "Third-person summary of what was decided and why. No direct quotes."
        },
        "context": {
          "type": "string",
          "description": "What the AI was doing at the moment of steering."
        }
      }
    }
  }
}

Examples

JSON

{
  "openjudgment": "0.1.0",
  "topic": "Implement auth middleware",
  "tool": "claude-code",
  "models": ["claude-sonnet-4-6"],
  "result": "completed",
  "moments": [
    {
      "timestamp": "2026-03-27T14:32:00.000Z",
      "type": "direction",
      "judgment": "Chose JWT over session-based auth to preserve stateless architecture.",
      "context": "Claude proposed session-based authentication."
    },
    {
      "timestamp": "2026-03-27T15:01:00.000Z",
      "type": "pushback",
      "judgment": "Rejected extracting token verification into a shared utility before any other callers existed.",
      "context": "Claude proposed extracting token verification into a reusable utility."
    }
  ]
}

Markdown

---
openjudgment: 0.1.0
tool: claude-code
models:
  - claude-sonnet-4-6
---

# Implement auth middleware

## 2026-03-27T14:32:00.000Z direction

### Judgment

Chose JWT over session-based auth to preserve stateless architecture.

### Context

Claude proposed session-based authentication.

## 2026-03-27T15:01:00.000Z pushback

### Judgment

Rejected extracting token verification into a shared utility before any other callers existed.

### Context

Claude proposed extracting token verification into a reusable utility.

**Result**: completed

Implementations

SteeringLog — Claude Code plugin that automatically produces OpenJudgment-conforming documents from live coding sessions. steeringlog.com