Ideogram JSON Validator

Ideogram 4 is a structured-JSON prompt model, and its schema has enough fiddly rules - three top-level keys must be present, global palettes cap at 16 colors, per-element palettes at 5, bounding boxes must stay within 0–1000 - that hand-built prompts quietly fail in ways that look fine to you and wrong to the model. IdeogramJSONValidator is the node you put at the end of the chain to catch all of it before you waste a generation.

It's the pack's quality gate. Every showcase workflow runs the assembled prompt through it on the way to the embedder, and the Visual Prompt Designer reuses it internally. Think of it as a linter for the Ideogram schema.

What it checks

The validator walks your prompt JSON against the schema's structural rules: valid JSON, presence of the three top-level keys, hex-color validity, global palette ≤ 16, per-element palettes ≤ 5, and bounding-box coordinates within 0–1000. It also does the pack's signature trick - reorders keys to the canonical order (aesthetics → lighting → color_palette inside style_description) because Ideogram is sensitive to key order in structured prompts.

Two inputs control its behavior:

• fix_key_order (BOOLEAN, default True) - whether to rewrite the key order while validating.
• strict_mode (BOOLEAN, default False) - when on, warnings also fail validation. Off by default because warnings are usually cosmetic (missing optional fields), and you don't want the gate to block a perfectly renderable prompt.

One principled detail worth knowing: it reorders keys only - it never edits content values. A wrong hex color isn't corrected; it's reported.

The outputs

• prompt_json - your prompt, key-reordered if fix_key_order was on. Wire this onward to generation/embedding.
• is_valid - BOOLEAN. The gate itself.
• report - a human-readable summary of what passed and what didn't.
• errors_json - a JSON array of error strings, for structured consumption.
• warnings_json - a JSON array of warning strings. These two were added after v1.1.1 for tooling that doesn't want to re-parse report's prose; existing wires to the first three outputs are unaffected.

Where it fits

... → IdeogramPromptAssembler → IdeogramJSONValidator → IdeogramMetadataEmbedder
                                        ↓
                                (is_valid / report to a text display)

The validator output is also the handiest debugging view in the pack. When a generation comes back wrong and you suspect the JSON, the report output tells you exactly which rule broke. If you're hand-authoring prompts, wire this in before you ever hit generate.

Installing it

Part of the pack. ComfyUI Manager: search "Ideogram Palette and Prompt Tools". Or:

cd ComfyUI/custom_nodes
git clone https://github.com/SurrealByDesign/ComfyUI-Ideogram-Palette-and-Prompt-Tools

Restart ComfyUI. Only extra dependency: scikit-learn (Manager handles it, or pip install scikit-learn). Nodes under Ideogram/Palette, Python ≥ 3.10, tested on ComfyUI 0.24.0 / Python 3.12.

Gotchas and troubleshooting

• is_valid False and you don't know why? Read report - it names the failing rule. That's the whole point of the node.
• Strict mode bites. Flip it on expecting "better" validation and suddenly a missing optional field fails the gate. Leave it off unless you genuinely want warnings to block.
• It validates structure, not taste. A valid prompt can still render badly. The validator guarantees schema compliance, not quality.
• Palette over 16 silently breaking your render? Not anymore - that's exactly what this catches. Run the style_json from IdeogramPaletteToGlobalJSON through here before merging.