---
id: node-definitions
title: "Node Definitions"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["Node Schema", "ComfyUI Node Structure"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.90
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법", "Node Definitions"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["workflow.json", "workflow_api.json", "object_info.json", "comfyui-workflow-to-api-converter-endpoint", "ComfyUI-WorkflowGenerator"]
github_commit: "bc85382, 82df278"
---

# [[Node Definitions]]

## 🎯 한 줄 통찰 (One-line insight)
노드 정의는 ComfyUI 워크플로우의 기능적 논리와 시각적 레이아웃을 결정하는 핵심 원자 단위로, 고유 ID와 입출력 스키마를 통해 복잡한 AI 프로세스를 유향 비순환 그래프(DAG)로 구조화한다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **고유 식별자 (Node ID):** 워크플로우 내에서 각 노드를 구분하는 고유한 숫자 또는 문자열 키(예: "#37")로, 그래프 순회 및 데이터 참조의 기준이 된다 [4, 5].
- **클래스 매핑 (Type/Class Type):** JSON의 `type` 또는 `class_type` 필드는 ComfyUI 백엔드 레지스트리에 등록된 특정 Python 클래스와 노드를 연결하여 실행 로직을 정의한다 [2, 6, 7].
- **입출력 슬롯 (I/O Slots):** 데이터 흐름을 위한 인터페이스로, `inputs`는 상위 노드의 출력을 참조하고 `outputs`는 하위 노드로 전달될 데이터 링크 정보를 포함한다 [4, 8].
- **위젯 및 속성 (Widgets & Properties):** 슬라이더, 텍스트 박스, 체크박스 등 사용자가 직접 입력한 값(`widgets_values`)과 노드의 내부 동작 설정을 저장한다 [2, 4, 9].

## 🧩 추출된 패턴 (Extracted patterns)
- **형식의 이분화 (Serialization Bifurcation):** 시각적 정보(위치, 크기, 그룹)를 포함하는 **Frontend 형식(workflow.json)**과 실행에 필요한 논리 정보만 남긴 **API 형식(workflow_api.json)**으로 나뉘어 관리된다 [10-12].
- **실행 모델 역전 (Execution Model Inversion):** 엔진은 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 역방향으로 그래프를 탐색하여 필요한 의존성 노드만 실행 리스트에 포함시킨다 [13].
- **메타데이터 임베딩 패턴:** 생성된 미디어(PNG, WebP)의 tEXt/zTXt 청크 내에 노드 그래프 JSON을 주입하여 파일 자체가 워크플로우 컨테이너 역할을 수행하도록 설계한다 [14-16].

## 📖 세부 내용 (Details)
ComfyUI 노드는 **JSON v1.0 스키마**에 따라 정밀하게 정의되며, 각 노드 객체는 다음과 같은 필수 속성을 보유해야 한다 [2, 17]:
- **id:** 그래프 순회를 위한 유효한 정수 또는 문자열 식별자 [2, 5].
- **type/class_type:** 노드의 기능을 결정하는 레지스트리 클래스명 [2, 6].
- **pos & size:** UI 캔버스 렌더링을 위한 좌표 `[x, y]` 및 차원 `[width, height]` 정보 (Frontend 전용) [2, 4].
- **widgets_values:** 사용자가 입력한 위젯 상태 값의 배열 또는 객체 [2, 4].
- **order:** 노드의 실행 또는 렌더링 우선순위를 나타내는 인덱스 [2].
- **mode:** 노드의 작동 상태(활성, 우회/Bypass 등)를 결정하는 수치 [2, 18].

**연결 구조(Connectivity):**
연결은 `inputs`와 `outputs` 배열을 통해 정의된다. `inputs` 내부의 `link` 속성은 들어오는 와이어의 고유 ID를 가리키며, API 형식에서는 이를 소스 노드 ID와 슬롯 인덱스의 쌍(예: `[19, 20]`)으로 직접 포함하기도 한다 [8, 9]. 슬롯 인덱싱은 다중 출력을 가진 노드(예: VAE Loader)에서 특정 데이터를 선택하는 데 필수적이다 [8].

**스키마 카탈로그 (object_info.json):**
실행 중인 인스턴스에서 사용 가능한 모든 노드의 입력/출력 타입, 필수/선택적 입력 항목, 기본값 및 툴팁 정보를 포함하는 레지스트리 역할을 한다 [21, 22]. 이는 워크플로우를 동적으로 생성하거나 검증하는 도구에서 참조 모델로 사용된다 [23].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **JSON 버전 차이:** 소스 데이터는 최신 버전인 **v1.0**을 언급하지만, 이전 버전인 **0.4**와의 호환성 문제나 업데이트 논의가 여전히 진행 중임을 암시한다 [17, 24].
- **대소문자 민감도 이슈:** ComfyUI 검증기가 콤보 위젯 값의 대소문자(예: "True" vs "true") 차이로 인해 실행을 거부하는 경우가 발생하여, 최신 변환 엔진에서는 이를 정규화(Normalization)하는 로직이 추가되었다 [25].
- **노드 식별 키의 차이:** Frontend JSON은 수치형 문자열을 ID로 사용하는 반면, API JSON은 이를 기능적 키로 활용하며 UI 메타데이터를 완전히 제거한다 [10, 11, 26].

## 🛠️ 적용 사례 (Applied in summary)
- **workflow.json / workflow_api.json:** 노드 정의가 실제로 구현되는 표준 파일 형식으로, RunComfy 및 Replicate와 같은 서비스에서 배포의 기초로 사용된다 [12, 21, 27].
- **object_info.json:** 실행 중인 서버의 `/object_info` 엔드포인트를 통해 실시간 노드 스키마를 제공한다 [23].
- **comfyui-workflow-to-api-converter-endpoint (v2.3.0):** 비-API 워크플로우를 API 형식으로 변환할 때 `COMFY_DYNAMICCOMBO_V3` 위젯 및 하위 입력을 처리하고 대소문자 문제를 해결하는 로직이 적용되었다 (Commit: `bc85382`) [25, 28-30].
- **ComfyUI-WorkflowGenerator:** 자연어 설명을 기반으로 `WorkflowGenerator` -> `NodeValidator` -> `WorkflowBuilder` 단계를 거쳐 노드 그래프를 동적으로 생성하며, `UpdateNodeCatalog` 노드를 통해 로컬 노드 레지스트리를 스캔한다 (Commit: `82df278`) [31-34].

## ✅ 검증 상태 및 신뢰도
- **상태:** 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.