Skip to content
MadooMadooDocs

madoo.image-typography/v1

Madoo professional still-image typography — Exact-font sizing, layout, safe-area and readability style for deterministic still-image text.
Reference madoo.image-typography/v1
Schema id urn:madoo:schema:image-typography:v1
Version 1.0.0
Served at GET /api/v1/json-schemas/madoo.image-typography/v1 · MCP get_json_schema

Where it appears

Section titled “Where it appears”
  • Saved in the parameter: image/text_overlay → typography

Fields

Section titled “Fields”
Field Type Required Rules Description
schema "madoo.image-typography/v1" yes
preset one of "minimal", "retail_price", "lower_third_still", "quote_card", "task_card", "custom" yes
font object yes no other fields
font.schema "madoo.font-reference/v1" yes
font.familyGuid string yes format “uuid”
font.versionGuid string yes format “uuid”
font.family string yes min length 1; max length 100
font.variant string yes min length 1; max length 100
font.weight integer yes ≥ 100; ≤ 900
font.style one of "normal", "italic" yes
font.fingerprint string yes pattern “^[0-9a-f]{64}$”
font.fallback object or null
size object yes no other fields
size.mode one of "fixed", "relative", "auto" yes
size.value number yes ≥ 1; ≤ 500
size.min number ≥ 8; ≤ 500
size.max number ≥ 8; ≤ 500
text object yes no other fields
text.color string yes pattern “^#[0-9A-Fa-f]{6}$”
text.opacity number yes ≥ 0; ≤ 1
text.transform one of "none", "uppercase", "lowercase" yes
text.letterSpacing number yes ≥ -10; ≤ 50
text.lineSpacing number yes ≥ 0.75; ≤ 3
layout object yes no other fields
layout.anchor one of "top-left", "top-center", "top-right", "center-left", "center", "center-right", "bottom-left", "bottom-center", "bottom-right" yes
layout.alignment one of "left", "center", "right" yes
layout.maxWidthPercent number yes ≥ 5; ≤ 100
layout.maxHeightPercent number yes ≥ 5; ≤ 100
layout.maxLines integer yes ≥ 1; ≤ 64
layout.offsetXPercent number yes ≥ -100; ≤ 100
layout.offsetYPercent number yes ≥ -100; ≤ 100
layout.overflow one of "fit", "fail", "clip" yes
layout.safeArea object yes no other fields
layout.safeArea.preset one of "none", "title-safe", "social-portrait", "custom" yes
layout.safeArea.topPercent number yes ≥ 0; ≤ 45
layout.safeArea.rightPercent number yes ≥ 0; ≤ 45
layout.safeArea.bottomPercent number yes ≥ 0; ≤ 45
layout.safeArea.leftPercent number yes ≥ 0; ≤ 45
outline object yes no other fields
outline.enabled boolean yes
outline.color string yes pattern “^#[0-9A-Fa-f]{6}$”
outline.width integer yes ≥ 0; ≤ 20
shadow object yes no other fields
shadow.enabled boolean yes
shadow.color string yes pattern “^#[0-9A-Fa-f]{6}$”
shadow.opacity number yes ≥ 0; ≤ 1
shadow.offsetX integer yes ≥ -100; ≤ 100
shadow.offsetY integer yes ≥ -100; ≤ 100
shadow.blur number yes ≥ 0; ≤ 20
background object yes no other fields
background.enabled boolean yes
background.color string yes pattern “^#[0-9A-Fa-f]{6}$”
background.opacity number yes ≥ 0; ≤ 1
background.paddingX integer yes ≥ 0; ≤ 200
background.paddingY integer yes ≥ 0; ≤ 200

The complete schema

Section titled “The complete schema”
madoo.image-typography/v1 (JSON Schema) 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:madoo:schema:image-typography:v1",
  "title": "Madoo professional still-image typography",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema",
    "preset",
    "font",
    "size",
    "text",
    "layout",
    "outline",
    "shadow",
    "background"
  ],
  "properties": {
    "schema": {
      "const": "madoo.image-typography/v1"
    },
    "preset": {
      "enum": [
        "minimal",
        "retail_price",
        "lower_third_still",
        "quote_card",
        "task_card",
        "custom"
      ]
    },
    "font": {
      "$ref": "#/$defs/fontReference"
    },
    "size": {
      "$ref": "#/$defs/size"
    },
    "text": {
      "$ref": "#/$defs/text"
    },
    "layout": {
      "$ref": "#/$defs/layout"
    },
    "outline": {
      "$ref": "#/$defs/outline"
    },
    "shadow": {
      "$ref": "#/$defs/shadow"
    },
    "background": {
      "$ref": "#/$defs/background"
    }
  },
  "$defs": {
    "fontReference": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "familyGuid",
        "versionGuid",
        "family",
        "variant",
        "weight",
        "style",
        "fingerprint"
      ],
      "properties": {
        "schema": {
          "const": "madoo.font-reference/v1"
        },
        "familyGuid": {
          "type": "string",
          "format": "uuid"
        },
        "versionGuid": {
          "type": "string",
          "format": "uuid"
        },
        "family": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "variant": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "weight": {
          "type": "integer",
          "minimum": 100,
          "maximum": 900,
          "multipleOf": 100
        },
        "style": {
          "enum": [
            "normal",
            "italic"
          ]
        },
        "fingerprint": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "fallback": {
          "type": [
            "object",
            "null"
          ]
        }
      }
    },
    "size": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mode",
        "value"
      ],
      "properties": {
        "mode": {
          "enum": [
            "fixed",
            "relative",
            "auto"
          ]
        },
        "value": {
          "type": "number",
          "minimum": 1,
          "maximum": 500
        },
        "min": {
          "type": "number",
          "minimum": 8,
          "maximum": 500
        },
        "max": {
          "type": "number",
          "minimum": 8,
          "maximum": 500
        }
      }
    },
    "text": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "color",
        "opacity",
        "transform",
        "letterSpacing",
        "lineSpacing"
      ],
      "properties": {
        "color": {
          "$ref": "#/$defs/color"
        },
        "opacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "transform": {
          "enum": [
            "none",
            "uppercase",
            "lowercase"
          ]
        },
        "letterSpacing": {
          "type": "number",
          "minimum": -10,
          "maximum": 50
        },
        "lineSpacing": {
          "type": "number",
          "minimum": 0.75,
          "maximum": 3
        }
      }
    },
    "layout": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "anchor",
        "alignment",
        "maxWidthPercent",
        "maxHeightPercent",
        "maxLines",
        "offsetXPercent",
        "offsetYPercent",
        "overflow",
        "safeArea"
      ],
      "properties": {
        "anchor": {
          "enum": [
            "top-left",
            "top-center",
            "top-right",
            "center-left",
            "center",
            "center-right",
            "bottom-left",
            "bottom-center",
            "bottom-right"
          ]
        },
        "alignment": {
          "enum": [
            "left",
            "center",
            "right"
          ]
        },
        "maxWidthPercent": {
          "type": "number",
          "minimum": 5,
          "maximum": 100
        },
        "maxHeightPercent": {
          "type": "number",
          "minimum": 5,
          "maximum": 100
        },
        "maxLines": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64
        },
        "offsetXPercent": {
          "type": "number",
          "minimum": -100,
          "maximum": 100
        },
        "offsetYPercent": {
          "type": "number",
          "minimum": -100,
          "maximum": 100
        },
        "overflow": {
          "enum": [
            "fit",
            "fail",
            "clip"
          ]
        },
        "safeArea": {
          "$ref": "#/$defs/safeArea"
        }
      }
    },
    "safeArea": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "preset",
        "topPercent",
        "rightPercent",
        "bottomPercent",
        "leftPercent"
      ],
      "properties": {
        "preset": {
          "enum": [
            "none",
            "title-safe",
            "social-portrait",
            "custom"
          ]
        },
        "topPercent": {
          "type": "number",
          "minimum": 0,
          "maximum": 45
        },
        "rightPercent": {
          "type": "number",
          "minimum": 0,
          "maximum": 45
        },
        "bottomPercent": {
          "type": "number",
          "minimum": 0,
          "maximum": 45
        },
        "leftPercent": {
          "type": "number",
          "minimum": 0,
          "maximum": 45
        }
      }
    },
    "outline": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "enabled",
        "color",
        "width"
      ],
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "color": {
          "$ref": "#/$defs/color"
        },
        "width": {
          "type": "integer",
          "minimum": 0,
          "maximum": 20
        }
      }
    },
    "shadow": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "enabled",
        "color",
        "opacity",
        "offsetX",
        "offsetY",
        "blur"
      ],
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "color": {
          "$ref": "#/$defs/color"
        },
        "opacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "offsetX": {
          "type": "integer",
          "minimum": -100,
          "maximum": 100
        },
        "offsetY": {
          "type": "integer",
          "minimum": -100,
          "maximum": 100
        },
        "blur": {
          "type": "number",
          "minimum": 0,
          "maximum": 20
        }
      }
    },
    "background": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "enabled",
        "color",
        "opacity",
        "paddingX",
        "paddingY"
      ],
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "color": {
          "$ref": "#/$defs/color"
        },
        "opacity": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "paddingX": {
          "type": "integer",
          "minimum": 0,
          "maximum": 200
        },
        "paddingY": {
          "type": "integer",
          "minimum": 0,
          "maximum": 200
        }
      }
    },
    "color": {
      "type": "string",
      "pattern": "^#[0-9A-Fa-f]{6}$"
    }
  }
}