Schemas for agentic workflows.

changelog.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["entries"],
  "$comment": "Changelog files are chronological mutation logs. Newest entries should appear first.",
  "properties": {
    "$schema": {
      "type": "string"
    },
    "entries": {
      "type": "array",
      "minItems": 1,
      "$comment": "Each item records one concrete change, backed by references and kept concise.",
      "items": {
        "type": "object",
        "required": [
          "id",
          "summary",
          "datetime",
          "type",
          "status",
          "references"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "pattern": "^cl_[a-z0-9_-]+$",
            "$comment": "Stable entry id. Keep it consistent when overwriting or referencing a record."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "$comment": "When the change was recorded. Use ISO 8601 so entries stay sortable."
          },
          "summary": {
            "type": "string",
            "minLength": 1,
            "maxLength": 180,
            "$comment": "Canonical one-line statement of what changed. Lead with the important effect."
          },
          "details": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000,
            "$comment": "Optional context, rationale, caveats, or rollout notes. Skip if the summary is enough."
          },
          "type": {
            "type": "string",
            "enum": ["addition", "removal", "change"],
            "$comment": "Classify the mutation so the log can be scanned quickly."
          },
          "status": {
            "type": "string",
            "enum": ["active", "reverted", "superseded"],
            "$comment": "Current state of the entry relative to the latest truth."
          },
          "references": {
            "type": "array",
            "minItems": 1,
            "$comment": "Source paths or URLs that ground the entry. Prefer the narrowest useful reference.",
            "items": {
              "type": "string",
              "pattern": "^(?=.*[A-Za-z._-])(?:~\/|\\.\\.\/|\/)?[^~\/#]+(?:\/[^~\/#]+)*(?:#L[0-9]+(?:-[0-9]+)?)?$"
            }
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

memory.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "entries"
  ],
  "properties": {
    "$schema": {
      "type": "string"
    },
    "entries": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "id",
          "summary",
          "type",
          "status",
          "scope",
          "sources"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "pattern": "^ml-[a-z0-9_-]+$",
            "$comment": "nanoid"
          },
          "summary": {
            "type": "string",
            "minLength": 1,
            "maxLength": 140,
            "$comment": "Single canonical statement; keep it short and stable."
          },
          "type": {
            "type": "string",
            "enum": [
              "rule",
              "preference",
              "pitfall",
              "decision",
              "constraint"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "stale",
              "superseded"
            ]
          },
          "scope": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^(?=.*[A-Za-z._-])(?:~\/|\\.\\.\/|\/)?[^~\/#]+(?:\/[^~\/#]+)*(?:#L[0-9]+(?:-[0-9]+)?)?$"
            },
            "$comment": "Where this memory applies. Keep the scope narrow."
          },
          "sources": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^(?=.*[A-Za-z._-])(?:~\\/|\\.\\.\\/|\\/)?[^~\\/#]+(?:\\/[^~\\/#]+)*\\.json(?:#cl_[a-z0-9_-]+)?$"
            },
            "$comment": "Evidence supporting the memory. Prefer the most specific changelog source available."
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}