2nd/10_Wiki/Topics/Comfyui/Serialization Formats.md

---
id: serialization-formats
title: "Serialization Formats"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["Workflow JSON Formats", "Frontend vs API Format"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["workflow.json", "workflow_api.json", "object_info.json", "bc85382"]
github_commit: "bc85382"
---

# [[Serialization Formats]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI 직렬화는 인간의 시각적 편집을 위한 **Frontend 포맷(UI 데이터 포함)**과 서버 및 스크립트 실행을 위한 **API 포맷(순수 로직)**으로 이원화되어 워크플로우의 가시성과 실행 효율성을 동시에 확보한다 [1-4].

## 🧠 핵심 개념 (Core concepts)
1.  **Frontend Format (workflow.json):** Litegraph 표준을 따르며 노드 위치, 크기, 그룹화 등 시각적 메타데이터를 포함하여 사용자 인터페이스 재구성을 지원한다 [1, 2, 5].
2.  **Backend/API Format (workflow_api.json):** 시각적 요소를 제거하고 노드 입력값과 연결 관계만 포함된 스트림라인 실행 그래프로, `/prompt` 엔드포인트를 통한 프로그래밍적 호출에 최적화되어 있다 [1, 2, 6].
3.  **Metadata Injection:** PNG 또는 WebP 이미지 생성 시, tEXt 또는 zTXt 청크 내부에 Frontend 워크플로우와 API 프롬프트 데이터를 직접 삽입하여 이미지를 워크플로우 컨테이너로 활용한다 [7-9].
4.  **Schema Specification (v1.0):** 노드 ID, 유형, 위치(pos), 크기(size), 실행 순서(order) 및 모드(mode) 등 그래프 무결성을 보장하기 위한 기술적 제약 조건을 정의한다 [10-12].

## 🧩 추출된 패턴 (Extracted patterns)
- **Bifurcation Pattern (이원화 패턴):** 동일한 로직을 시각적 레이아웃용(Frontend)과 실행용(API)으로 분리하여 저장함으로써 사용자 경험과 API 확장성을 분리하여 관리한다 [1, 2].
- **Link Embedding Strategy:** API 포맷에서는 명시적인 연결 객체 대신 노드 입력 필드 내에 '기원 노드 ID'와 '출력 슬롯 인덱스'를 직접 참조(예: `[13, 14]`)하여 그래프 구조를 단순화한다 [1, 15].
- **Schema Validation Pattern:** `object_info.json`을 통해 실행 인스턴스의 노드 스키마(입출력 유형, 범위 등)를 카탈로그화하고, 실행 전 `validate_prompt` 함수로 워크플로우의 유효성을 검증한다 [16-18].

## 📖 세부 내용 (Details)
- **Frontend JSON 구조 및 특징:**
    - 노드 식별을 위해 고유한 시각적 ID(숫자 문자열)를 사용하며, 노드가 축소되거나 고정되었는지와 같은 시각적 플래그를 유지한다 [1, 19].
    - `links` 배열을 별도로 두어 노드 간의 물리적 연결 관계를 정의하며, 6개 항목으로 구성된 배열 형식을 통해 기원/대상 노드 및 슬롯 정보를 명시한다 [3, 11, 19].

- **API JSON 구조 및 특징:**
    - 불필요한 UI 메타데이터를 제거하여 파일 크기를 압축하고 전송 효율을 높인다 [1, 2, 6].
    - 키값은 노드 ID로 구성되며, 각 값은 `class_type`과 `inputs`를 포함한 객체이다. 입력 필드에는 위젯 값 또는 다른 노드로부터의 링크 참조가 포함된다 [6, 18, 20].

- **메타데이터 저장 방식:**
    - PNG 파일의 경우, ComfyUI는 워크플로우(Frontend)와 프롬프트(API)를 별개의 문자열로 저장한다. 이는 이미지를 UI로 드래그했을 때 시각적 편집이 가능하게 함과 동시에 프로그래밍적 재실행을 가능하게 하는 중복 구조를 제공한다 [8].
    - 단, 이미지 편집 소프트웨어나 소셜 미디어 플랫폼을 거칠 경우 이러한 비필수 메타데이터 청크가 손실될 위험이 크다 [8, 21].

- **기타 주요 직렬화 아티팩트:**
    - `object_info.json`: 실행 중인 ComfyUI 인스턴스의 모든 노드 스키마 등록부로, 입출력 유형, 허용 범위, 툴팁 등을 포함하여 도구 개발이나 입력값 검증에 사용된다 [5, 17, 18].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **하위 호환성 문제:** ComfyUI가 빈번하게 업데이트됨에 따라, 이전 버전에서 생성된 JSON 파일이 최신 버전의 ComfyUI에서 제대로 작동하지 않을 수 있다는 점이 명시되어 있다 [22].
- **데이터 유실 가능성:** 이미지 기반 직렬화는 편리하지만, 압축 소프트웨어나 네트워크 전송 시 메타데이터가 제거될 수 있어 JSON 파일 형태의 별도 저장이 권장된다 [8, 22, 23].

## 🛠️ 적용 사례 (Applied in summary)
- **workflow.json & workflow_api.json:** ComfyUI의 표준 저장 포맷으로 사용되며, RunComfy 및 Mystic 등 서버리스 API 배포 플랫폼의 기본 참조 파일로 활용된다 [1, 17, 24].
- **object_info.json:** 실행 인스턴스에서 스키마 정보를 추출하기 위해 `https://<server_id>/object_info` 엔드포인트를 통해 접근 가능하다 [25].
- **comfyui-workflow-to-api-converter-endpoint:** Frontend 포맷의 워크플로우를 서버 측에서 실시간으로 API 포맷으로 변환하는 기능을 구현한 커스텀 노드 프로젝트이다 [26].
- **Git Commit bc85382:** 콤보 위젯 값의 대소문자 표기 오류(예: "True" vs "true")가 유효성 검사에서 거부되는 문제를 해결하기 위해 대소문자 구분 없는 매칭 로직이 적용되었다 [27, 28].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능)
- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM)
- **중복 검사 결과:** 신규 생성 (New discovery)

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