json-render는 Vercel Labs에서 개발한 오픈 소스 라이브러리로, 최종 사용자가 자연어 프롬프트(prompt)를 통해 사용자 인터페이스(UI), 대시보드, 위젯, 데이터 시각화 등을 생성할 수 있도록 지원하면서도, 개발자가 정의한 구성 요소(components) 및 동작(actions) 내에서 안전하게 제한되도록 보장하는 것을 목표로 합니다. 이는 AI가 생성하는 UI 출력의 예측 불가능성과 잠재적 위험성을 해결하기 위한 핵심 방법론을 제공합니다.

이 라이브러리의 핵심 방법론은 다음과 같은 세 가지 원칙을 기반으로 합니다:

1. Guardrailed (제한적 AI): AI는 개발자가 미리 정의한 '카탈로그(catalog)' 내의 구성 요소와 액션만을 사용할 수 있습니다. 이 카탈로그는 AI가 "말할 수 있는" 어휘를 제한함으로써, 생성되는 UI가 항상 안전하고 의도한 대로 동작하도록 보장합니다.
2. Predictable (예측 가능한 출력): AI가 생성하는 출력은 항상 개발자가 정의한 스키마(schema)에 부합하는 JSON 형식입니다. 이는 AI가 임의의 코드를 생성하거나 예상치 못한 구조를 만들 위험을 제거합니다.
3. Fast (빠른 렌더링): AI 응답이 생성되는 동안 스트리밍(streaming) 방식으로 점진적으로 UI를 렌더링할 수 있어 사용자 경험을 향상시킵니다.

핵심 워크플로우 및 기술적 상세:

프로젝트의 구현은 세 가지 주요 단계로 구성됩니다:

4. 카탈로그 정의 (Define Your Catalog):
   • 개발자는 @json-render/core의 createCatalog 함수를 사용하여 AI가 사용할 수 있는 구성 요소와 액션을 선언합니다.
   • 각 구성 요소는 zod와 같은 스키마 유효성 검사 라이브러리를 사용하여 props의 데이터 타입을 엄격하게 정의합니다. 예를 들어, Card 구성 요소는 title: z.string()과 같은 속성을 가질 수 있으며, hasChildren: true를 통해 중첩된 자식 요소를 허용할지 지정합니다.
   • Metric 구성 요소는 valuePath: z.string()과 같이 동적으로 데이터를 바인딩할 경로를 정의할 수 있습니다.
   • Button 구성 요소는 action: ActionSchema와 같이 AI가 의도하는 동작을 선언할 수 있도록 ActionSchema를 따르는 action 속성을 가집니다.
   • 액션(actions) 또한 export_report, refresh_data와 같은 이름과 설명을 포함하여 정의됩니다. 이는 AI가 사용자의 의도를 시스템 내의 구체적인 비즈니스 로직과 연결하는 접점을 제공합니다.

5. 구성 요소 등록 (Register Your Components):
   • 개발자는 카탈로그에서 정의된 JSON 구조를 실제 렌더링 가능한 UI로 변환하기 위해 React와 같은 UI 프레임워크를 사용하여 해당 구성 요소들을 구현하고 등록합니다.
   • registry 객체는 JSON 트리의 type 필드에 매핑되는 React 함수형 구성 요소들을 포함합니다.
   • 예를 들어, JSON에 { "type": "Card", "props": { "title": "Revenue" } }가 있다면, 등록된 Card React 컴포넌트가 해당 title prop을 사용하여 렌더링됩니다.
   • 구성 요소는 element prop을 통해 AI가 생성한 JSON 노드에 접근하고, onAction과 같은 콜백을 통해 AI가 정의한 액션을 처리할 수 있습니다.

6. AI 생성 및 렌더링 (Let AI Generate):
   • @json-render/react 패키지에서 제공하는 useUIStream 훅을 사용하여 AI 서비스와의 통신을 관리합니다. 이 훅은 AI로부터 스트리밍되는 JSON 트리를 받아옵니다.
   • DataProvider는 UI 구성 요소가 동적으로 데이터를 조회할 수 있도록 초기 데이터를 제공합니다.
   • ActionProvider는 AI가 선언한 액션(예: export_report, refresh_data)에 대한 실제 JavaScript 함수를 매핑하여 제공합니다.
   • Renderer 구성 요소는 useUIStream에서 반환된 tree (JSON 형식의 UI 구조)와 등록된 components (React 컴포넌트 레지스트리)를 받아 실제로 UI를 렌더링합니다.

주요 기능 (Features):

• Conditional Visibility (조건부 가시성): visible 속성을 사용하여 데이터, 인증 상태 또는 복잡한 논리에 따라 구성 요소의 표시 여부를 제어할 수 있습니다. and, not, path (데이터 경로 바인딩), auth (인증 상태) 등의 논리 연산자를 지원하여 동적인 UI 규칙을 정의합니다. 예: {"visible": {"auth": "signedIn"}}
• Rich Actions (풍부한 액션): AI가 생성하는 액션은 단순히 이름뿐만 아니라 params (데이터 바인딩), confirm (확인 대화 상자), onSuccess, onError 콜백을 포함할 수 있습니다. 이는 AI가 사용자 상호작용 후 성공 또는 실패에 따라 UI 상태를 업데이트하거나 추가 작업을 수행할 수 있도록 합니다. 예: {"onSuccess": {"set": {"/ui/success": true}}}
• Built-in Validation (내장 유효성 검사): TextField와 같은 입력 구성 요소에 checks 배열을 사용하여 required, email과 같은 내장 유효성 검사 함수와 커스텀 오류 메시지를 정의할 수 있습니다. validateOn 속성을 통해 유효성 검사 시점(예: blur)을 지정할 수 있습니다.

동작 원리 요약:

json-render는 사용자의 자연어 프롬프트를 AI에게 전달하고, AI는 개발자가 정의한 카탈로그(Guardrails)를 기반으로 예측 가능한 JSON 트리를 생성합니다. 이 JSON 트리는 @json-render/react의 Renderer에 의해 개발자가 구현한 React 구성 요소로 매핑되어 안전하고 효율적으로 UI로 렌더링됩니다. 이를 통해 AI의 잠재력을 활용하여 UI를 자동 생성하면서도, 개발자가 설정한 경계 내에서 일관성과 제어력을 유지할 수 있습니다.