{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://venugopinath.me/cecilias-notes/schemas/inkbook/v1.json",
  "title": "Inkbook Schema v1",
  "description": "JSON Schema specification for the Cecilia's Notes .inkbook v1 format.",
  "type": "object",
  "required": [
    "version",
    "id",
    "title",
    "subject",
    "created_at",
    "updated_at",
    "pages"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "description": "Self-referential schema URL, should equal https://venugopinath.me/cecilias-notes/schemas/inkbook/v1.json"
    },
    "version": {
      "type": "string",
      "const": "1",
      "description": "Format version. Must be '1' for v1."
    },
    "id": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
      "description": "Unique UUID identification for the notebook. Case-insensitive on read; writers SHOULD emit uppercase to match Swift's UUID().uuidString."
    },
    "title": {
      "type": "string",
      "description": "User-facing title of the notebook."
    },
    "subject": {
      "type": "string",
      "description": "Free-form subject tag. The app creates a Subject by this name on import if missing."
    },
    "created_at": {
      "$ref": "#/$defs/utc_timestamp",
      "description": "Creation timestamp in UTC, second precision."
    },
    "updated_at": {
      "$ref": "#/$defs/utc_timestamp",
      "description": "Last modified timestamp in UTC, second precision."
    },
    "cover_tone": {
      "type": "string",
      "enum": [
        "parchment",
        "studio-white",
        "ash",
        "coal",
        "midnight",
        "moss",
        "dusk",
        "ink-black"
      ],
      "description": "Selected cover color tone style."
    },
    "page_template": {
      "type": "string",
      "enum": [
        "blank",
        "lined",
        "grid",
        "dot-grid",
        "cornell",
        "music"
      ],
      "description": "Default background guide template for pages."
    },
    "page_size": {
      "type": "string",
      "enum": [
        "a4",
        "letter",
        "ipad-canvas"
      ],
      "description": "Dimensions target size for rendering note canvas."
    },
    "agent": {
      "type": "object",
      "required": [
        "written_by",
        "tool",
        "tool_version"
      ],
      "properties": {
        "written_by": {
          "type": "string",
          "description": "Name or identifier of the writer agent, e.g. 'cecilias-notes-mcp'."
        },
        "model": {
          "type": "string",
          "description": "Underlying model identifier if generated by an LLM."
        },
        "tool": {
          "type": "string",
          "description": "The specific MCP tool or system function used to write the notebook."
        },
        "tool_version": {
          "type": "string",
          "description": "Version string of the tool."
        }
      },
      "description": "Metadata tracking the tool or agent that authored/modified this file."
    },
    "pages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/page"
      },
      "description": "List of pages within the notebook, ordered chronologically or sequentially."
    },
    "mcp_action": {
      "type": "string",
      "enum": [
        "create",
        "append",
        "replace"
      ],
      "description": "v1.1+ optimistic-concurrency field. Older writers may omit. Declares the intent of the writer."
    },
    "base_updated_at": {
      "$ref": "#/$defs/utc_timestamp",
      "description": "The updated_at value the writer read before producing this file. Required iff mcp_action is 'append' and strict concurrency validation is requested."
    }
  },
  "$defs": {
    "utc_timestamp": {
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$",
      "description": "ISO-8601 UTC timestamp with second precision, e.g., YYYY-MM-DDTHH:MM:SSZ"
    },
    "page": {
      "type": "object",
      "required": [
        "id",
        "index",
        "blocks"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
          "description": "Unique UUID identifier for this page."
        },
        "index": {
          "type": "integer",
          "minimum": 0,
          "description": "0-based sorting index of the page in the notebook."
        },
        "created_at": {
          "type": "string",
          "description": "ISO-8601 creation timestamp for the page (optional)."
        },
        "blocks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/block"
          },
          "description": "Rich content blocks layout on the page."
        }
      }
    },
    "block": {
      "type": "object",
      "required": [
        "type"
      ],
      "anyOf": [
        {
          "properties": {
            "type": {
              "const": "heading"
            },
            "content": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            }
          },
          "required": [
            "content",
            "level"
          ]
        },
        {
          "properties": {
            "type": {
              "const": "paragraph"
            },
            "content": {
              "type": "string"
            }
          },
          "required": [
            "content"
          ]
        },
        {
          "properties": {
            "type": {
              "const": "list"
            },
            "style": {
              "type": "string",
              "enum": [
                "bullet",
                "numbered"
              ]
            },
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "style",
            "items"
          ]
        },
        {
          "properties": {
            "type": {
              "const": "code"
            },
            "content": {
              "type": "string"
            },
            "language": {
              "type": "string"
            }
          },
          "required": [
            "content"
          ]
        },
        {
          "properties": {
            "type": {
              "const": "divider"
            }
          }
        },
        {
          "properties": {
            "type": {
              "const": "quote"
            },
            "content": {
              "type": "string"
            },
            "attribution": {
              "type": "string"
            }
          },
          "required": [
            "content"
          ]
        },
        {
          "properties": {
            "type": {
              "const": "callout"
            },
            "content": {
              "type": "string"
            },
            "kind": {
              "type": "string",
              "enum": [
                "note",
                "warning",
                "tip"
              ]
            }
          },
          "required": [
            "content",
            "kind"
          ]
        },
        {
          "description": "Tolerate unknown block types (skip during parsing rather than failing validation)",
          "properties": {
            "type": {
              "type": "string",
              "not": {
                "enum": [
                  "heading",
                  "paragraph",
                  "list",
                  "code",
                  "divider",
                  "quote",
                  "callout"
                ]
              }
            }
          }
        }
      ]
    }
  }
}