{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/capacities-io/json-schema/capacities-io-api-block-schema.json",
  "title": "ApiBlock",
  "description": "A block in a Capacities object (text, code, grid, entity embed, etc.). Nested via `blocks` or grid `columns`.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/capacities-io-openapi.json#/components/schemas/ApiBlock",
  "oneOf": [
    {
      "$ref": "#/$defs/ApiTextBlock"
    },
    {
      "$ref": "#/$defs/ApiGroupBlock"
    },
    {
      "$ref": "#/$defs/ApiGridBlock"
    },
    {
      "$ref": "#/$defs/ApiCodeBlock"
    },
    {
      "$ref": "#/$defs/ApiMathBlock"
    },
    {
      "$ref": "#/$defs/ApiEntityBlock"
    },
    {
      "$ref": "#/$defs/ApiHorizontalLineBlock"
    },
    {
      "$ref": "#/$defs/ApiUnsupportedBlock"
    }
  ],
  "type": "object",
  "$defs": {
    "ApiBlock": {
      "description": "A block in a Capacities object (text, code, grid, entity embed, etc.). Nested via `blocks` or grid `columns`.",
      "oneOf": [
        {
          "$ref": "#/$defs/ApiTextBlock"
        },
        {
          "$ref": "#/$defs/ApiGroupBlock"
        },
        {
          "$ref": "#/$defs/ApiGridBlock"
        },
        {
          "$ref": "#/$defs/ApiCodeBlock"
        },
        {
          "$ref": "#/$defs/ApiMathBlock"
        },
        {
          "$ref": "#/$defs/ApiEntityBlock"
        },
        {
          "$ref": "#/$defs/ApiHorizontalLineBlock"
        },
        {
          "$ref": "#/$defs/ApiUnsupportedBlock"
        }
      ],
      "type": "object"
    },
    "ApiCodeBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "CodeBlock"
          ]
        },
        "lang": {
          "type": "string"
        },
        "text": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "lang",
        "text"
      ],
      "additionalProperties": false,
      "description": "Fenced code block with language and source text."
    },
    "ApiCodeTokenOutput": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "CodeToken"
          ]
        },
        "text": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "text"
      ],
      "additionalProperties": false,
      "description": "Inline code span."
    },
    "ApiDatePayload": {
      "type": "object",
      "properties": {
        "dateResolution": {
          "type": "string",
          "enum": [
            "time",
            "day"
          ],
          "description": "`day` or `time`."
        },
        "start": {
          "description": "ISO 8601 start.",
          "type": [
            "string",
            "null"
          ]
        },
        "end": {
          "description": "ISO 8601 end, if any.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "dateResolution",
        "start",
        "end"
      ],
      "additionalProperties": false,
      "description": "Date value."
    },
    "ApiEntityBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "EntityBlock"
          ]
        },
        "entityId": {
          "type": [
            "string",
            "null"
          ]
        },
        "date": {
          "description": "Date value when the embed targets a UtilDate object.",
          "allOf": [
            {
              "$ref": "#/$defs/ApiDatePayload"
            }
          ]
        }
      },
      "required": [
        "id",
        "type",
        "entityId"
      ],
      "additionalProperties": false,
      "description": "Embedded Capacities object reference, or null when empty."
    },
    "ApiGridBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "GridBlock"
          ]
        },
        "columns": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/ApiBlock"
            }
          }
        },
        "dividers": {
          "type": "array",
          "items": {
            "type": "number"
          }
        },
        "gridLayout": {
          "type": "string",
          "enum": [
            "columns",
            "grid"
          ]
        },
        "colorTheme": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "text-gray",
                "text-rose",
                "text-pink",
                "text-fuchsia",
                "text-purple",
                "text-violet",
                "text-indigo",
                "text-blue",
                "text-sky",
                "text-cyan",
                "text-teal",
                "text-emerald",
                "text-green",
                "text-lime",
                "text-yellow",
                "text-amber",
                "text-orange",
                "text-red"
              ]
            },
            {
              "type": "string",
              "enum": [
                "bg-gray",
                "bg-rose",
                "bg-pink",
                "bg-fuchsia",
                "bg-purple",
                "bg-violet",
                "bg-indigo",
                "bg-blue",
                "bg-sky",
                "bg-cyan",
                "bg-teal",
                "bg-emerald",
                "bg-green",
                "bg-lime",
                "bg-yellow",
                "bg-amber",
                "bg-orange",
                "bg-red"
              ]
            }
          ]
        }
      },
      "required": [
        "id",
        "type",
        "columns",
        "dividers"
      ],
      "additionalProperties": false,
      "description": "Multi-column layout; each column is an array of blocks."
    },
    "ApiGroupBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "GroupBlock"
          ]
        },
        "blocks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ApiBlock"
          }
        },
        "list": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bullet",
                "alphabetical",
                "numerical",
                "roman"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        "todo": {
          "type": "object",
          "properties": {
            "isDone": {
              "type": "boolean"
            }
          },
          "required": [
            "isDone"
          ],
          "additionalProperties": false
        },
        "toggle": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "isOpen": {
              "type": "boolean"
            }
          },
          "required": [
            "isOpen"
          ],
          "additionalProperties": false
        },
        "colorTheme": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "text-gray",
                "text-rose",
                "text-pink",
                "text-fuchsia",
                "text-purple",
                "text-violet",
                "text-indigo",
                "text-blue",
                "text-sky",
                "text-cyan",
                "text-teal",
                "text-emerald",
                "text-green",
                "text-lime",
                "text-yellow",
                "text-amber",
                "text-orange",
                "text-red"
              ]
            },
            {
              "type": "string",
              "enum": [
                "bg-gray",
                "bg-rose",
                "bg-pink",
                "bg-fuchsia",
                "bg-purple",
                "bg-violet",
                "bg-indigo",
                "bg-blue",
                "bg-sky",
                "bg-cyan",
                "bg-teal",
                "bg-emerald",
                "bg-green",
                "bg-lime",
                "bg-yellow",
                "bg-amber",
                "bg-orange",
                "bg-red"
              ]
            }
          ]
        }
      },
      "required": [
        "id",
        "type",
        "blocks"
      ],
      "additionalProperties": false,
      "description": "Container block that groups nested blocks (e.g. list or toggle group)."
    },
    "ApiHighlight": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "webhighlights",
            "readwise",
            "kindle-import",
            "custom"
          ]
        },
        "url": {
          "description": "Source URL associated with this highlight, if any.",
          "type": "string"
        },
        "label": {
          "description": "Display label; present for custom highlights.",
          "type": "string"
        },
        "location": {
          "description": "Location text shown below the block; present for custom highlights (max 20 characters).",
          "type": "string",
          "maxLength": 20
        },
        "color": {
          "description": "Highlight color stored as annotation metadata.",
          "type": "string",
          "enum": [
            "yellow",
            "orange",
            "green",
            "red",
            "purple",
            "blue"
          ]
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false,
      "description": "Highlight annotation attached to a text block."
    },
    "ApiHorizontalLineBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "HorizontalLineBlock"
          ]
        }
      },
      "required": [
        "id",
        "type"
      ],
      "additionalProperties": false,
      "description": "Horizontal divider line."
    },
    "ApiLinkToken": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "LinkToken"
          ]
        },
        "text": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "entityId": {
          "description": "Referenced object id when the link targets a Capacities object.",
          "type": "string"
        },
        "date": {
          "description": "Date value when the link targets a UtilDate object.",
          "allOf": [
            {
              "$ref": "#/$defs/ApiDatePayload"
            }
          ]
        }
      },
      "required": [
        "type",
        "text"
      ],
      "additionalProperties": false,
      "description": "Hyperlink with display text and optional URL, object reference, or date."
    },
    "ApiMathBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "MathBlock"
          ]
        },
        "text": {
          "type": "string"
        },
        "colorTheme": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "text-gray",
                "text-rose",
                "text-pink",
                "text-fuchsia",
                "text-purple",
                "text-violet",
                "text-indigo",
                "text-blue",
                "text-sky",
                "text-cyan",
                "text-teal",
                "text-emerald",
                "text-green",
                "text-lime",
                "text-yellow",
                "text-amber",
                "text-orange",
                "text-red"
              ]
            },
            {
              "type": "string",
              "enum": [
                "bg-gray",
                "bg-rose",
                "bg-pink",
                "bg-fuchsia",
                "bg-purple",
                "bg-violet",
                "bg-indigo",
                "bg-blue",
                "bg-sky",
                "bg-cyan",
                "bg-teal",
                "bg-emerald",
                "bg-green",
                "bg-lime",
                "bg-yellow",
                "bg-amber",
                "bg-orange",
                "bg-red"
              ]
            }
          ]
        }
      },
      "required": [
        "id",
        "type",
        "text"
      ],
      "additionalProperties": false,
      "description": "Display math block (LaTeX)."
    },
    "ApiMathTokenOutput": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "MathToken"
          ]
        },
        "text": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "text"
      ],
      "additionalProperties": false,
      "description": "Inline math (LaTeX)."
    },
    "ApiTextBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "TextBlock"
          ]
        },
        "tokens": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ApiToken"
          }
        },
        "blocks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ApiBlock"
          }
        },
        "hierarchy": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            },
            "val": {
              "type": "number"
            }
          },
          "required": [
            "key",
            "val"
          ],
          "additionalProperties": false
        },
        "list": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bullet",
                "alphabetical",
                "numerical",
                "roman"
              ]
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        "todo": {
          "type": "object",
          "properties": {
            "isDone": {
              "type": "boolean"
            }
          },
          "required": [
            "isDone"
          ],
          "additionalProperties": false
        },
        "toggle": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "isOpen": {
              "type": "boolean"
            }
          },
          "required": [
            "isOpen"
          ],
          "additionalProperties": false
        },
        "quote": {
          "type": "object",
          "properties": {
            "layout": {
              "type": "string",
              "enum": [
                "normal",
                "standout"
              ]
            }
          },
          "required": [
            "layout"
          ],
          "additionalProperties": false
        },
        "colorTheme": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "text-gray",
                "text-rose",
                "text-pink",
                "text-fuchsia",
                "text-purple",
                "text-violet",
                "text-indigo",
                "text-blue",
                "text-sky",
                "text-cyan",
                "text-teal",
                "text-emerald",
                "text-green",
                "text-lime",
                "text-yellow",
                "text-amber",
                "text-orange",
                "text-red"
              ]
            },
            {
              "type": "string",
              "enum": [
                "bg-gray",
                "bg-rose",
                "bg-pink",
                "bg-fuchsia",
                "bg-purple",
                "bg-violet",
                "bg-indigo",
                "bg-blue",
                "bg-sky",
                "bg-cyan",
                "bg-teal",
                "bg-emerald",
                "bg-green",
                "bg-lime",
                "bg-yellow",
                "bg-amber",
                "bg-orange",
                "bg-red"
              ]
            }
          ]
        },
        "highlight": {
          "description": "Highlight annotation attached to this block, if any.",
          "allOf": [
            {
              "$ref": "#/$defs/ApiHighlight"
            }
          ]
        }
      },
      "required": [
        "id",
        "type",
        "tokens",
        "blocks",
        "hierarchy"
      ],
      "additionalProperties": false,
      "description": "Paragraph or heading with inline tokens and optional nested blocks."
    },
    "ApiTextTokenOutput": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "TextToken"
          ]
        },
        "text": {
          "type": "string"
        },
        "style": {
          "type": "object",
          "properties": {
            "bold": {
              "type": "boolean"
            },
            "italic": {
              "type": "boolean"
            },
            "strikethrough": {
              "type": "boolean"
            },
            "underline": {
              "type": "boolean"
            }
          },
          "additionalProperties": false
        },
        "color": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "text-gray",
                "text-rose",
                "text-pink",
                "text-fuchsia",
                "text-purple",
                "text-violet",
                "text-indigo",
                "text-blue",
                "text-sky",
                "text-cyan",
                "text-teal",
                "text-emerald",
                "text-green",
                "text-lime",
                "text-yellow",
                "text-amber",
                "text-orange",
                "text-red"
              ]
            },
            {
              "type": "string",
              "enum": [
                "bg-gray",
                "bg-rose",
                "bg-pink",
                "bg-fuchsia",
                "bg-purple",
                "bg-violet",
                "bg-indigo",
                "bg-blue",
                "bg-sky",
                "bg-cyan",
                "bg-teal",
                "bg-emerald",
                "bg-green",
                "bg-lime",
                "bg-yellow",
                "bg-amber",
                "bg-orange",
                "bg-red"
              ]
            }
          ]
        }
      },
      "required": [
        "type",
        "text",
        "style"
      ],
      "additionalProperties": false,
      "description": "Plain text with optional bold, italic, strikethrough, underline, and color."
    },
    "ApiToken": {
      "oneOf": [
        {
          "$ref": "#/$defs/ApiTextTokenOutput"
        },
        {
          "$ref": "#/$defs/ApiLinkToken"
        },
        {
          "$ref": "#/$defs/ApiMathTokenOutput"
        },
        {
          "$ref": "#/$defs/ApiCodeTokenOutput"
        }
      ],
      "description": "Inline token inside a TextBlock.",
      "type": "object"
    },
    "ApiUnsupportedBlock": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "unsupported"
          ]
        },
        "blockType": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type",
        "blockType"
      ],
      "additionalProperties": false,
      "description": "Placeholder for block types not available in the API."
    }
  }
}