2nd/10_Wiki/Topics/Comfyui/Workflow JSON v1.0 Schema.md

---
id: workflow-json-v1.0-schema
title: "Workflow JSON v1.0 Schema"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["ComfyUI JSON Schema", "Workflow v1.0 Specification"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.90
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법", "Schema", "JSON"]
raw_sources: ["NotebookLM Synthesis"]
applied_in:
  - "/specs/workflow_json"
  - "/src/scripts/metadata"
  - "comfyui-workflow-to-api-converter-endpoint"
  - "ComfyUI-to-Python-Extension"
github_commit: "bc85382"
---

# [[Workflow JSON v1.0 Schema]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI 워크플로우 JSON은 생성 로직을 **유도 비순환 그래프(DAG)**로 구조화하여 시각적 인터페이스와 실행 엔진 사이의 상호운용성을 보장하는 핵심 데이터 규격이다 [1, 2].

## 🧠 핵심 개념 (Core concepts)
- **이원적 직렬화 포맷 (Bifurcation of Formats):** 시각적 편집과 레이아웃 보존을 위한 **Frontend Format**(workflow.json)과 서버 측 실행에 최적화된 **Backend/API Format**(workflow_api.json)으로 구분된다 [3-5].
- **Litegraph 표준 기반:** 프론트엔드 포맷은 노드 위치, 크기, 그룹화 등 시각적 메타데이터를 포함하는 Litegraph 표준을 따른다 [3, 6].
- **슬롯 기반 연결성 (Slot-based Connectivity):** 노드 간 데이터 흐름은 고유한 입력/출력 슬롯 인덱스를 통해 정의되며, API 포맷에서는 이를 노드 내부에 인라인 참조로 내장한다 [3, 7, 8].
- **JSON Schema v1.0 (Draft-07):** 기술적 무결성을 검증하기 위해 필수 속성과 데이터 타입을 규정하는 최신 공식 사양이다 [9-11].

## 🧩 추출된 패턴 (Extracted patterns)
- **Metadata Redundancy 패턴:** PNG 파일 내에 시각적 포맷(workflow)과 실행 포맷(prompt)을 동시에 내장하여, 이미지 한 장만으로 편집과 재실행이 모두 가능하도록 설계되었다 [12, 13].
- **Execution Model Inversion:** 최종 출력 노드(Save Image 등)에서 역방향으로 그래프를 탐색하여 실행에 필요한 의존성 노드만 식별하고 불필요한 연산을 배제한다 [14].
- **Node Functional Mapping:** API 포맷에서 링크 객체를 제거하고 `[노드ID, 슬롯번호]` 형태의 배열로 간소화하여 전송 효율과 파싱 속도를 극대화한다 [3, 15, 16].

## 📖 세부 내용 (Details)
### 1. 노드 객체 속성 (Node Object Properties)
v1.0 스키마에 정의된 노드 객체는 그래프 탐색 및 렌더링을 위해 다음과 같은 속성을 포함해야 한다 [8, 9]:
- **id:** 그래프 내 노드를 식별하는 고유 정수 또는 문자열 [9].
- **type (또는 class_type):** 노드 레지스트리에 등록된 클래스 이름과 매핑되는 식별자 [9, 16].
- **pos & size:** 캔버스상의 좌표 및 크기 정보를 담은 배열 (API 포맷에서는 제거됨) [9, 16].
- **widgets_values:** 텍스트 박스, 슬라이더 등 사용자 입력값을 저장하는 배열 [9, 15].
- **order & mode:** 실행/렌더링 우선순위 및 노드의 활성 상태(예: bypass)를 정의한다 [8, 9].

### 2. 그래프 연결 구조 (Link and Slot Connectivity)
- **연결 정의:** 노드의 `inputs` 배열은 유입되는 선의 ID를 참조하며, `outputs` 배열은 여러 하위 노드로 연결될 수 있는 링크 ID들의 배열을 포함한다 [7].
- **슬롯 인덱싱:** 특정 노드의 출력(예: VAE Loader의 VAE 출력)이 정확히 어떤 슬롯에서 생성되어 소비되는지 명시하는 것이 필수적이다 [7].
- **API 포맷의 특수성:** `workflow_api.json`은 시각적 링크 배열을 제거하고, 노드 입력 필드 내에 직접 `["노드ID", 슬롯_인덱스]` 값을 할당하여 실행 그래프를 평탄화(Flattening)한다 [3, 15].

### 3. 보조 스키마 (object_info.json)
- 실행 중인 ComfyUI 인스턴스의 모든 노드에 대한 스키마 카탈로그이다 [5, 17].
- 각 노드가 허용하는 입력 유형, 범위, 출력 데이터 타입 및 툴팁 정보를 포함하여 외부 도구에서 JSON을 동적으로 생성하거나 검증할 때 사용된다 [17-19].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **버전 호환성 문제:** 소스에 따르면 현재 v1.0이 최신이지만, ComfyUI의 잦은 업데이트로 인해 0.4 버전 등 이전 버전의 JSON 파일이 최신 환경에서 정상 작동하지 않을 수 있음이 지적된다 [10, 11, 20].
- **데이터 파편화:** 이미지 메타데이터에서 추출한 JSON은 종종 커스텀 노드 정보를 누락할 수 있으며, 이 경우 캔버스에 'Red Boxes' 에러가 발생한다 [21-23].
- **API 포맷의 가독성:** 실행 최적화된 API JSON은 시각적 정보가 모두 제거된 'Skeleton' 형태이므로, 이를 다시 ComfyUI 인터페이스로 드래그하여 편집하기에는 부적합하다 [24, 25].

## 🛠️ 적용 사례 (Applied in summary)
- **ComfyUI 공식 사양:** `/specs/workflow_json` 경로에서 v1.0 규격을 공식 관리한다 [10].
- **프론트엔드 메타데이터 처리:** `ComfyUI_frontend/src/scripts/metadata`에서 자바스크립트 기반의 메타데이터 파싱 로직을 구현하고 있다 [26].
- **comfyui-workflow-to-api-converter-endpoint:** 서버 측 파이썬 로직을 통해 Frontend JSON을 API JSON 규격으로 실시간 변환하며, `bc85382` 커밋에서 콤보 위젯 값의 정규화 이슈가 해결되었다 [24, 27-29].
- **ComfyUI-to-Python-Extension:** JSON 워크플로우를 분석하여 동일한 로직의 `.py` 실행 스크립트를 생성할 때 v1.0 스키마 구조를 참조한다 [30, 31].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (공식 문서 기반의 스펙 정의 완료)
- **출처 신뢰도:** B (Official Documentation 및 전문 기술 블로그 기반)
- **중복 검사 결과:** 신규 생성

## 🔗 관련 문서 링크

### 상위/유사 개념
- [[Comfyui workflow json 생성 방법]]
  - 연결 이유: 본 스키마가 생성 방법론의 기술적 기반이 됨.
- [[Dev mode Options]]
  - 연결 이유: 스키마의 두 가지 형태(Frontend/API) 중 API 포맷을 내보내기 위한 필수 전제 조건임.

#### [아키텍처/기반 기술]
- [[Litegraph Standard]]
  - 연결 이유: Frontend JSON의 데이터 구조와 렌더링 방식을 규정함.
- [[Execution Model Inversion]]
  - 연결 이유: JSON 그래프를 해석하여 효율적으로 실행하는 백엔드 최적화 원리임.

#### [구현/활용 도구]
- [[ComfyUI Manager]]
  - 연결 이유: JSON 스키마 내의 `class_type`을 분석하여 누락된 커스텀 노드를 복구함.
- [[ComfyUI-to-Python-Extension]]
  - 연결 이유: JSON 워크플로우를 파이썬 코드로 이식하는 실제 사례임.

### 심층 후속 질문 (Deeper Research Questions)
- API 포맷에서 링크를 노드 입력 내부에 인라인화하는 방식이 순환 참조(Circular Reference) 방지에 어떤 기여를 하는가?
- `object_info.json`의 스키마 데이터와 실제 노드의 `INPUT_TYPES` 메서드 사이의 동기화 실패 시 어떤 예외 처리가 발생하는가?
- v1.0 스키마에서 `widgets_values` 배열의 순서 기반 데이터 저장이 노드 업데이트로 인한 위젯 추가 시 어떤 호환성 문제를 일으키는가?
- PNG 파일의 `tEXt` 청크 용량 제한이 매우 거대한 워크플로우 JSON(예: 수백 개의 노드) 저장에 한계로 작용하는가?
- `comfy-pack`과 같은 도구에서 사용하는 모델 해싱 기술이 JSON 스키마 내에서 어떻게 표준화될 수 있는가?

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** 외부 애플리케이션(Unity, Web App 등)에서 ComfyUI 서버에 작업을 요청할 때 API JSON을 생성하고 전송해야 한다 [28, 32].
- **System Design:** 워크플로우 자동화를 위해 JSON 내의 특정 노드 ID와 입력 필드(예: 프롬프트, 시드)를 동적으로 수정하는 로직을 설계할 수 있다 [33, 34].
- **Operation / Maintenance:** 커스텀 노드 업데이트 시 JSON 내 `class_type` 명칭이 변경되면 워크플로우가 파손될 수 있으므로 버전 관리가 필요하다 [20, 35].
- **Learning Path:** 노드 기반 인터페이스의 데이터 구조를 이해하면 시각적 툴 없이도 순수 코드로 생성 AI 파이프라인을 구축할 수 있다 [30, 36].

### 인접 주변 주제 (Adjacent Topics)
- [[Custom Nodes]]
  - 확장 방향: JSON 스키마에 새로운 노드 타입을 등록하고 관리하는 방법 연구.
- [[Metadata Stripping]]
  - 확장 방향: 소셜 미디어 배포 시 이미지 내 메타데이터 손실 대응 방안 및 외부 JSON 저장 전략.

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.