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

---
id: json-schema-v1.0
title: "JSON Schema v1.0"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["ComfyUI Workflow JSON v1.0"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법", "JSON Schema"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["/specs/workflow_json"]
github_commit: ""
---

# [[JSON Schema v1.0]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI 워크플로우 JSON v1.0은 Draft-07 사양을 준수하며, 노드 기반의 생성형 AI 파이프라인을 시각적 메타데이터와 실행 논리로 이원화하여 직렬화하는 표준 규격이다 [1, 2].

## 🧠 핵심 개념 (Core concepts)
- **Draft-07 Specification:** ComfyUI 워크플로우 JSON의 구조적 무결성을 보장하는 최신 공식 스키마 표준이다 [2].
- **데이터 이원화 (Bifurcation):** 사용자 인터페이스용 'Frontend Format'과 서버 실행용 'API Format'으로 나뉘어 관리된다 [1, 3].
- **노드 객체 속성 (Node Object Properties):** 각 노드는 ID, 유형, 위치(pos), 크기(size), 위젯 값(widgets_values) 등의 필수 및 선택적 속성을 정의해야 한다 [2, 4].
- **슬롯 및 링크 연결성 (Slot & Link Connectivity):** 노드 간의 데이터 흐름은 고유한 링크 ID와 입력/출력 슬롯 인덱싱을 통해 정의된다 [5].

## 🧩 추출된 패턴 (Extracted patterns)
- **실행 모델 반전 (Execution Model Inversion):** 엔진이 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색, 필요한 의존성만 식별하여 실행하는 최적화 패턴을 따른다 [6].
- **메타데이터 임베딩 (Metadata Embedding):** PNG 파일의 tEXt 또는 zTXt 청크에 Frontend와 API 포맷의 JSON 데이터를 동시에 저장하여 시각적 편집과 프로그래밍적 재실행을 모두 지원한다 [7-9].
- **버전 호환성 제약:** 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 ComfyUI 버전에서 정상 작동하지 않을 수 있는 패턴이 관찰된다 [10].

## 📖 세부 내용 (Details)
ComfyUI 워크플로우 JSON v1.0은 복잡한 노드 네트워크를 이식 가능하고 사람이 읽을 수 있는 형태의 데이터로 변환하는 핵심 메커니즘이다 [11, 12].

**1. 노드 객체의 기술적 구성**
- **필수 속성:** `id`(그래프 탐색용 고유 식별자), `type`(노드 레지스트리의 클래스 이름 매핑), `pos` 및 `size`(UI 렌더링용 좌표 및 크기), `order`(실행 또는 렌더링 순서), `mode`(활성/바이패스 상태)가 포함된다 [2].
- **선택적 속성:** 사용자가 입력한 슬라이더, 텍스트 박스 등의 값을 저장하는 `widgets_values`가 존재한다 [2].

**2. 포맷별 구조적 차이**
- **Frontend JSON (workflow.json):** 시각적 편집을 위해 Litegraph 표준을 따르며, 노드 위치, 그룹 구조, 색상 등 모든 시각적 메타데이터를 포함한다 [1, 3, 13].
- **API JSON (workflow_api.json):** 서버 사이드 처리에 최적화된 스트림라인 실행 그래프이다 [1]. 시각적 데이터를 제거하고 노드 입력 내에 링크를 직접 임베딩하여 효율성을 극대화한다 [1, 3, 14].

**3. 연결 메커니즘**
- 연결은 `links` 배열 내에서 정의되며, 각 항목은 일반적으로 `origin_id`, `origin_slot`, `target_id`, `target_slot`을 정의하는 6개 항목 배열 또는 구조화된 객체이다 [5].
- 슬롯 인덱싱은 매우 엄격하여, 특정 노드의 여러 출력 슬롯 중 정확히 어떤 데이터가 다운스트림 노드에 소비되는지 명시해야 한다 [5].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **JSON 포맷의 취약성:** PNG 메타데이터에 포함된 JSON은 표준 이미지 편집기나 소셜 미디어 플랫폼에서 압축/편집 시 삭제되기 쉬운 취약점이 있다 [9].
- **버전 간 비호환성:** 소스에 따르면 ComfyUI의 빈번한 업데이트로 인해 구버전 JSON이 최신 버전에서 작동하지 않을 수 있으며, 이를 해결하기 위해 ComfyUI Manager 등의 도구가 의존성을 해결해야 한다 [10, 15].
- **필드 명칭 차이:** Frontend 포맷에서는 `type`을 사용하지만 API 포맷에서는 `class_type`이라는 명칭을 사용하여 노드를 식별한다 [3, 16].

## 🛠️ 적용 사례 (Applied in summary)
- **공식 문서 경로:** `/specs/workflow_json` 위치에 JSON Schema v1.0 명세가 정의되어 있다 [17].
- **버전 관리:** 현재 가장 최신 규격은 Version 1.0이며, 이전 버전인 0.4와 구분되어 관리된다 [18].
- **유효성 검사 도구:** `comfyui-workflow-to-api-converter-endpoint` 커스텀 노드는 서버 사이드에서 비-API 워크플로우를 v1.0 API 포맷으로 변환하는 기능을 구현하고 있다 [19, 20].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (공식 명세 및 개발 문서 기반으로 구조화됨) [2, 21]
- **출처 신뢰도:** B (공식 문서 및 기본 소스 기반)
- **중복 검사 결과:** 신규 생성 (New discovery)


## 🔗 관련 문서 링크 (Related document links)

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Draft-07 Specification]]
  - 연결 이유: JSON Schema v1.0이 기반으로 삼고 있는 기술 표준이다 [2].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터의 유효성 검사 규칙 및 구조적 제약 조건.
- [[Node-based Visual Programming]]
  - 연결 이유: JSON Schema가 표현하고자 하는 추상화된 프로그래밍 모델이다 [11, 22].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드와 링크가 실제 프로그램 논리로 변환되는 원리.

#### [구현/활용 도구]
- [[API JSON (workflow_api.json)]]
  - 연결 이유: v1.0 스키마가 실제로 실행 환경에서 가장 많이 활용되는 형태이다 [1, 14].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 서버리스 배포 및 API 호출 시의 데이터 최적화 방법.
- [[Frontend JSON (workflow.json)]]
  - 연결 이유: v1.0 스키마의 시각적 메타데이터를 포함하는 전체 데이터셋이다 [1, 13].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 사용자 인터페이스 상에서의 워크플로우 재구성과 공유.

### 심층 후속 질문 (Deeper Research Questions)
- v1.0 스키마에서 Draft-07 규격이 구체적으로 어떤 유효성 검사 과정을 거쳐 노드 실행 전 오류를 방지하는가? [2]
- Frontend JSON의 시각적 메타데이터(pos, size)가 실제 백엔드 실행 엔진에 전혀 영향을 주지 않는 구조적 이유는 무엇인가? [1, 3]
- 링크 데이터 표현 방식(6개 항목 배열)에서 각 인덱스가 담고 있는 기술적 의미는 무엇인가? [5]
- [[Execution Model Inversion]] 패턴이 적용될 때, JSON 내에서 사용되지 않는 노드는 어떤 과정을 통해 무시되는가? [6]
- API 포맷에서 `class_type`이 아닌 `inputs` 내에 링크 정보가 포함되는 방식이 실행 속도에 미치는 영향은 무엇인가? [1, 3]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** Python의 `json` 라이브러리를 사용하여 노드 ID를 추적하고 `widgets_values`를 동적으로 수정하여 자동화된 이미지 생성을 구현할 수 있다 [23, 24].
- **System Design:** 외부 애플리케이션에서 ComfyUI를 호출할 때, `workflow_api.json` 형식을 사용하여 불필요한 UI 데이터를 배제하고 전송 효율을 높인다 [1, 25].
- **Operation / Maintenance:** `ComfyUI Manager`를 통해 JSON 내의 `class_type`을 파싱하여 누락된 커스텀 노드를 자동으로 설치하고 관리할 수 있다 [15].
- **Learning Path:** 시각적 워크플로우를 먼저 이해한 후, 개발자 모드를 활성화하여 API 전용 JSON 포맷의 데이터 구조를 분석하는 단계로 학습이 진행된다 [26, 27].

### 인접 주변 주제 (Adjacent Topics)
- [[Object_info.json]]
  - 확장 방향: 실행 중인 ComfyUI 인스턴스의 노드 스키마 카탈로그를 이해하여 JSON을 동적으로 생성하는 도구 제작 [28, 29].
- [[Metadata Stripping]]
  - 확장 방향: 이미지 파일 공유 시 발생하는 워크플로우 데이터 손실 방지 및 복구 전략 [9, 19].

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