Complete schema specification for artifact envelope, node types, validation rules, and serialization constraints

Artifact Schema Reference

Complete schema specification for the Artifacts platform - validated JSON structure for LLM-generated documents.

Artifact Envelope - Root structure and required fields
Node Structure - Common fields for all node types
Implemented Node Types - All valid node types (3 total)
Responsive Gap System - Space tokens and breakpoints
Validation Points - Where validation happens in the system
Serialization Constraints - JSON-serializable requirements
Node Type Registry - Complete list of valid types

Artifact Envelope

An artifact is a JSON structure with validated schema:

{
  id: string,           // UUID (generated by database)
  title: string,        // Human-readable title
  version: number,      // Version number (currently always 1)
  nodes: ArtifactNode[] // Array of layout/content nodes
}

Constraint: nodes array must contain at least one node.

Node Structure

Every node must have:

{
  id: string,                    // Unique within artifact
  kind: 'layout' | 'content',    // Node category
  type: string,                  // Specific node type
  props: object,                 // Type-specific props
  children?: ArtifactNode[]      // Only for layout nodes
}

Constraints:

id must be unique within the artifact tree
kind + type combination must match an implemented node type
props must match the exact schema for that node type
Extra properties are rejected (all schemas use .strict())
children only allowed for layout nodes
Layout nodes must have at least one child

Implemented Node Types

Layout Nodes (1 type)

vstack - Vertical flex container

{
  id: string,
  kind: 'layout',
  type: 'vstack',
  props: {
    gap?: ResponsiveGap,
    align?: 'start' | 'center' | 'end' | 'stretch',
    justify?: 'start' | 'center' | 'end' | 'space-between' | 'space-around'
  },
  children: ArtifactNode[] // minimum 1
}

Content Nodes (2 types)

markdown - GFM rendering

{
  id: string,
  kind: 'content',
  type: 'markdown',
  props: {
    markdown: string // GFM-formatted markdown
  }
}

line-chart - Recharts line chart

{
  id: string,
  kind: 'content',
  type: 'line-chart',
  props: {
    xLabel?: string,
    yLabel?: string,
    series: Array<{
      id: string,
      label: string,
      color?: 'blue' | 'green' | 'violet' | 'orange' | 'red',
      curve?: 'linear' | 'monotone' | 'step' | 'stepBefore' | 'stepAfter'
    }>,
    data: Array<{
      x: string | number,
      values: Record<string, number | null>
    }>
  }
}

Responsive Gap System

type SpaceToken = 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';

type ResponsiveGap = {
  base: SpaceToken; // Required base value
  sm?: SpaceToken; // Optional 640px+ override
  md?: SpaceToken; // Optional 768px+ override
  lg?: SpaceToken; // Optional 1024px+ override
  xl?: SpaceToken; // Optional 1280px+ override
};

Validation Points

MCP Tool Input: artifact.create validates nodes array against artifactNodeSchema
Service Layer: createArtifactStore().create() validates full structure with artifactStructureSchema.parse()
Database: Postgres JSONB column stores validated structure
Renderer: Artifact component assumes pre-validated structure

Serialization Constraints

Props must be JSON-serializable:

✅ Strings, numbers, booleans, null
✅ Arrays and plain objects
✅ Nested structures
❌ Functions
❌ undefined (use null instead)
❌ Circular references
❌ Date objects (serialize to ISO string)
❌ RegExp, Map, Set, etc.

Node Type Registry

Only these 3 node types are valid:

vstack (layout)
markdown (content)
line-chart (content)

Any other type value will fail validation.

Schema Reference