{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/blinkpdf-io/json-schema/blinkpdf-io-render-body-typography-schema.json",
  "title": "Font role selection",
  "description": "The family each text role paints in: `body`, `heading`, and up to 2 `named` roles each bind a hosted weighted key, a declared Google Fonts display name, or the `blink://asset/<sha256>` handle of a font uploaded with prepare_upload; `pool` and `variantMap` choose which Google Fonts weights load and paint.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/blinkpdf-io-stamp-api-openapi.yml#/components/schemas/Render.Body.typography",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "body": {
      "$ref": "#/$defs/Render.Body.typography.body"
    },
    "heading": {
      "$ref": "#/$defs/Render.Body.typography.body"
    },
    "pool": {
      "minItems": 1,
      "maxItems": 4,
      "description": "Optional override of families parsed from `googleFontsUrls` (max 4 distinct names)",
      "type": "array",
      "items": {
        "additionalProperties": false,
        "description": "Optional override of a family parsed from `googleFontsUrls` (weights and italic flag)",
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "pattern": "^[A-Za-z][A-Za-z0-9 ]{0,63}$",
            "description": "Google Fonts family display name",
            "type": "string"
          },
          "weights": {
            "minItems": 1,
            "maxItems": 9,
            "description": "Explicit upright weights to declare for this family (sorted ascending, unique)",
            "type": "array",
            "items": {
              "minimum": 100,
              "maximum": 900,
              "multipleOf": 100,
              "description": "Font weight on the CSS scale in steps of 100: one of 100, 200, 300, 400, 500, 600, 700, 800, 900 (intermediate values like 450 are not valid weights)",
              "type": "integer"
            }
          },
          "italic": {
            "description": "Whether to fetch italic cuts alongside the requested CSS weights",
            "type": "boolean"
          }
        }
      }
    },
    "named": {
      "minItems": 1,
      "maxItems": 2,
      "description": "Up to 2 custom roles binding a pool family, a hosted key, or an uploaded font handle to a name, referenced by a rule `set.font` (`<role>.<variant>`) and by `variantMap.role`",
      "type": "array",
      "items": {
        "additionalProperties": false,
        "description": "Binds a custom role name to a hosted key, a pool display name, or an uploaded font handle",
        "type": "object",
        "required": [
          "role",
          "family"
        ],
        "properties": {
          "role": {
            "pattern": "^[a-z][a-z0-9-]{0,15}$",
            "description": "Custom role identifier referenced by a `FontKey` and by rule `set.family`. Lowercase kebab-case (a leading letter, then lowercase letters, digits, or hyphens, max 16 chars), e.g. `accent`, `code-emphasis` — not camelCase or snake_case, so it can appear in a `<role>.<variant>` font key",
            "type": "string"
          },
          "family": {
            "$ref": "#/$defs/Render.Body.typography.body"
          }
        }
      }
    },
    "headingVariant": {
      "description": "Hosted heading ladder policy. Applies only when the heading family is a hosted weighted key. Omit or `bold` loads the registry heading cuts (Inter: SemiBold base H1–H6, Bold via strong). `regular` forces body-symmetric heading slots (same faces as body). A Google Fonts or uploaded-font heading ignores this field",
      "type": "string",
      "enum": [
        "regular",
        "bold"
      ]
    },
    "variantMap": {
      "minItems": 1,
      "maxItems": 16,
      "description": "Per-family variant-to-weight mapping. Each entry optionally narrows by `role` (body/heading/named) and, for headings, by `depth`. Resolution is by specificity: depth > role > family. Up to 16 entries to allow multiple (role, depth) slots per family.",
      "type": "array",
      "items": {
        "additionalProperties": false,
        "type": "object",
        "required": [
          "family"
        ],
        "properties": {
          "family": {
            "pattern": "^[A-Za-z][A-Za-z0-9 ]{0,63}$",
            "description": "Google Fonts family the variant map applies to",
            "type": "string"
          },
          "role": {
            "description": "Semantic role the weights apply to. Omitted = family-wide (current behavior). `depth` further narrows `role: \"heading\"`.",
            "anyOf": [
              {
                "const": "body",
                "type": "string"
              },
              {
                "const": "heading",
                "type": "string"
              },
              {
                "pattern": "^[a-z][a-z0-9-]{0,15}$",
                "description": "Custom role declared in `typography.named` (e.g. `display`)",
                "type": "string"
              }
            ]
          },
          "depth": {
            "description": "Heading depth(s) the weights apply to (1–6). Only valid with `role: \"heading\"`. A single int or an array (OR). An entry with `depth` wins over a role-only entry, which wins over a family-only entry.",
            "anyOf": [
              {
                "minimum": 1,
                "maximum": 6,
                "type": "integer"
              },
              {
                "minItems": 1,
                "maxItems": 6,
                "type": "array",
                "items": {
                  "minimum": 1,
                  "maximum": 6,
                  "type": "integer"
                }
              }
            ]
          },
          "regular": {
            "minimum": 100,
            "maximum": 900,
            "multipleOf": 100,
            "description": "Font weight on the CSS scale in steps of 100: one of 100, 200, 300, 400, 500, 600, 700, 800, 900 (intermediate values like 450 are not valid weights)",
            "type": "integer"
          },
          "italic": {
            "minimum": 100,
            "maximum": 900,
            "multipleOf": 100,
            "description": "Font weight on the CSS scale in steps of 100: one of 100, 200, 300, 400, 500, 600, 700, 800, 900 (intermediate values like 450 are not valid weights)",
            "type": "integer"
          },
          "bold": {
            "minimum": 100,
            "maximum": 900,
            "multipleOf": 100,
            "description": "Font weight on the CSS scale in steps of 100: one of 100, 200, 300, 400, 500, 600, 700, 800, 900 (intermediate values like 450 are not valid weights)",
            "type": "integer"
          },
          "boldItalic": {
            "minimum": 100,
            "maximum": 900,
            "multipleOf": 100,
            "description": "Font weight on the CSS scale in steps of 100: one of 100, 200, 300, 400, 500, 600, 700, 800, 900 (intermediate values like 450 are not valid weights)",
            "type": "integer"
          }
        }
      }
    }
  },
  "$defs": {
    "Render.Body.typography.body": {
      "title": "Typography role family",
      "description": "The family a typography role is bound to: a hosted weighted key, a declared Google Fonts display name, a `typography.named` role reference, or the `blink://asset/<sha256>` handle of a font uploaded with `prepare_upload` (`kind: \"font\"`)",
      "anyOf": [
        {
          "const": "inter",
          "type": "string"
        },
        {
          "const": "lora",
          "type": "string"
        },
        {
          "const": "source-serif-4",
          "type": "string"
        },
        {
          "pattern": "^[A-Za-z][A-Za-z0-9 ]{0,63}$",
          "description": "Google Fonts display name from the declared pool (e.g. `Playfair Display`)",
          "type": "string"
        },
        {
          "pattern": "^[a-z][a-z0-9-]{0,15}$",
          "description": "Reference to a custom role declared in `typography.named` (e.g. `display`)",
          "type": "string"
        },
        {
          "pattern": "^[Bb][Ll][Ii][Nn][Kk]://[Aa][Ss][Ss][Ee][Tt]/[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])",
          "description": "Handle `blink://asset/<sha256>` of a TrueType or OpenType CFF font uploaded through the MCP (`prepare_upload` with `kind: \"font\"`, then `complete_upload`) under the calling credential. The handle names one face, and that face is the whole family: its weight (OS/2 weight class) and italic style are read from the font, and a `weight`, `italic`, or `<role>.<variant>` request for any other cut is rejected at validate",
          "type": "string"
        }
      ]
    }
  }
}