comfyui-json-nodes

Composable ComfyUI nodes for building, merging, previewing, and validating JSON objects and arrays.

Installation

Clone this repository into your ComfyUI custom_nodes directory:

cd <ComfyUI>/custom_nodes
git clone <repo-url> comfyui-json-nodes

Restart ComfyUI. The nodes appear in the utils/json category.

Nodes

JSON Field (JsonFieldNode)

Create one typed JSON field fragment for use in Merge or Root.

Input	Type	Default	Details
key	STRING	none	Dot-separated path. Supports nested objects (camera.lens), array indexes (subjects[0].name), and hyphenated keys (lens-mm).
type	COMBO	string	One of string, int, float, boolean, array, object.
array_separator	COMBO	newline	Optional schema input used when type=array. The frontend hides or shows the same widget based on type, and the backend normalizes positional execution when ComfyUI omits this hidden optional slot. Options: newline, comma.
value	STRING	""	Multiline value input. Parsed according to type.

Output	Type	Details
FIELD_JSON	STRING	JSON object fragment such as {"camera": {"lens-mm": 85}}.

Behavior:

• Empty key raises an error.
• int requires a whole number.
• float rejects NaN and infinities.
• boolean treats 1, true, yes, and on as true; everything else is false.
• array accepts JSON array syntax directly or splits plain text by the selected separator with best-effort coercion for ints, floats, booleans, and null.
• object requires a valid JSON object.
• Sparse array paths are padded with null, so subjects[2].description produces [null, null, {...}].
• Field errors are reported as human-readable key/value errors.

Quick JSON (JsonObjectFromFieldsNode)

Build a small object from inline entries without separate Field nodes.

Input	Type	Default	Details
entry_0 ... entry_7	STRING	""	Optional entry slots. UI labels them as entry 1 through entry 8. Format: key=value or key: value.
pretty_print	BOOLEAN	true	Pretty-print the output JSON.

Output	Type	Details
JSON_TEXT	STRING	Final JSON object string.

Behavior:

• Blank entries are ignored.
• Values stay as strings; Quick JSON does not type-coerce.
• Entries are processed in numeric order, and later duplicates overwrite earlier ones.
• Invalid entry syntax raises an error that points to the expected key=value or key: value format.

JSON Array Merge (JsonArrayMergeNode)

Build a JSON array from autogrow inputs.

Input	Type	Default	Details
items	AUTOGROW STRING inputs	at least 1	ComfyUI creates item_1 ... item_64 inputs as needed. Each connected input is parsed as JSON first; if parsing fails, the value is included as plain text.
pretty_print	BOOLEAN	true	Pretty-print the output JSON.

Output	Type	Details
JSON_ARRAY	STRING	Final JSON array string.

Behavior:

• Inputs are collected in numeric autogrow order (item_1, item_2, ...).
• Valid JSON values keep their parsed types, including objects, arrays, numbers, booleans, null, and quoted JSON strings.
• Plain text inputs fall back to JSON string values.

JSON Object Merge (JsonObjectMergeNode)

Merge multiple JSON object strings using autogrow inputs.

Input	Type	Default	Details
objects	AUTOGROW STRING inputs	at least 2	ComfyUI creates json_object_1 ... json_object_64 inputs as needed. Each connected input must contain a JSON object string.
duplicate_key_policy	COMBO	error	One of error, overwrite, keep_first.
pretty_print	BOOLEAN	true	Pretty-print the output JSON.

Output	Type	Details
JSON_TEXT	STRING	Merged JSON object string.

Behavior:

• Inputs are merged in numeric autogrow order (json_object_1, json_object_2, ...).
• Nested objects are deep-merged.
• Non-object inputs or invalid JSON raise readable errors.
• Duplicate key conflicts use the selected policy:
• error: fail with messages like Duplicate key 'name' in object 1 and object 2.
• overwrite: later input wins.
• keep_first: first value wins.

JSON Root Object (JsonRootObjectNode)

Output node that merges field/object fragments, validates them, and shows a live preview in the UI.

Input	Type	Default	Details
objects	AUTOGROW STRING inputs	at least 1	ComfyUI creates json_input_1 ... json_input_64 inputs as needed. Each connected input must contain a JSON object string.
preview_json	STRING	{}	Internal preview channel used by the frontend. The node execution ignores its value; the frontend keeps it read-only.
duplicate_key_policy	COMBO	error	One of error, overwrite, keep_first.
schema_json	STRING	""	Optional JSON Schema-like object. Supports type, required, properties, enum, pattern, and items.
strict_mode	BOOLEAN	false	When enabled, object keys not declared in properties are rejected.
pretty_print	BOOLEAN	true	Pretty-print the output JSON.

Output	Type	Details
JSON_TEXT	STRING	Final merged JSON object string.

Behavior:

• Root merges connected inputs in numeric autogrow order.
• Duplicate-key handling uses the selected policy, with human-readable source labels such as field 1 and field 2.
• If schema_json is provided, it must be a JSON object. If its top-level type is omitted, Root treats it as object.
• Supported schema types are any, string, int, float, boolean, array, and object.
• strict_mode applies while validating nested objects too.
• Validation errors use clearer schema wording, for example missing required fields, type mismatches, unexpected keys, invalid schema JSON, and duplicate-key conflicts.
• The frontend keeps preview_json read-only and serializable, appends a runtime-only Create Schema button, and relabels connected root inputs from attached field keys when possible.
• Create Schema infers int, float, boolean, string, object, array, and any from the current preview. Mixed arrays and empty arrays become items: { "type": "any" }.

Settings

Open ComfyUI Settings -> JSON Nodes to set defaults for new nodes:

Setting	Type	Default	Applies to
Default strict mode	Boolean	false	JSON Root Object
Default pretty print	Boolean	true	Quick JSON, JSON Array Merge, JSON Object Merge, JSON Root Object
Default array separator	newline / comma	newline	JSON Field
Default duplicate key policy	error / overwrite / keep_first	error	JSON Object Merge, JSON Root Object

These defaults apply when a node is created. Existing workflows keep their saved values.

Development

Frontend source lives in src/ and is bundled with Bun to web/js/jsonNodes.js. Backend nodes live in nodes/ with helpers in utils/.

Typical development flow:

bun install
bun x tsc --noEmit
bun run bun.build.ts
python -m pytest tests/ -v
node tests/test_frontend_preview.mjs
make ci

Other useful targets:

make build
make typecheck
make lint
make format
make test
make integration
make release
make clean

Notes:

• make ci runs the repository's build, typecheck, lint, unit-test, frontend-test, and integration-test targets.
• make test currently runs Python unittest discovery plus node tests/test_frontend_preview.mjs.
• python -m pytest tests/ -v also works in this repo because pyproject.toml and conftest.py are configured for pytest.

Tooling requirements:

• Bun for the TypeScript frontend build
• Node.js for the frontend preview test
• Pytest for the direct Python test command above
• Ruff for Python formatting and linting
• Biome for the committed JavaScript/MJS lint/format pass
• Python 3.10+ for the backend tests

License

MIT