Files

T

2026-05-19 18:08:09 +09:00

8.5 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

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)

상위/유사 개념

[아키텍처/기반 기술]

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.

8.5 KiB Raw Blame History