immerschema 1.0.7

JSON-Schema & taxonomy for Fulldome pipelines

Immersive Projects CG Pipeline Schema Suite

A JSON Schema designed to ensure consistent data structure across production pipelines.

🌟 Features

• Core shot schema – validates every scene or sub-scene with detailed metadata
• Project schema – wraps all shots for whole-show validation and global settings
• Enum packs – single source of truth for techniques, risk flags, screen zones, and more
• Taxonomy packs – human-friendly categorization for UI components
• LLM I/O schema – guarantees safe, auditable AI edits
• Comprehensive examples – real-world usage patterns and edge cases
• Automated testing – full validation suite with edge case coverage
• ESM/CommonJS Support – dual module format support for modern Node.js environments

📦 Installation

# npm
npm install immerschema@1.0.7

# pip
pip install immerschema==1.0.7

�� Project Structure

immerschema/
├── schemas/                    # Core JSON Schema files
│   ├── core.schema.json       # Individual shot validation
│   ├── project.schema.json    # Project-level validation
│   ├── enum/                  # Enumeration schemas
│   │   ├── technique.enum.json
│   │   ├── screenzone.enum.json
│   │   ├── riskflag.enum.json
│   │   ├── role.enum.json
│   │   └── software.enum.json
│   ├── ext/                   # Extension schemas
│   ├── io/                    # Input/Output schemas
│   └── taxonomy/              # Taxonomy definitions
├── examples/                   # Comprehensive examples
│   ├── simple_project.json    # Minimal valid project
│   ├── comprehensive_project.json  # Full-featured project
│   ├── ai_generated_shot.json # AI-focused techniques
│   ├── live_action_shot.json  # Photography/live-action
│   └── audio_reactive_shot.json    # Audio-reactive content
├── test/                      # Test files and validation
│   ├── test_project.json      # Legacy test project
│   ├── test_shot.json         # Legacy test shot
│   ├── validation_tests.json  # Comprehensive validation tests
│   └── edge_cases.json        # Edge cases and boundary tests
└── scripts/
    └── test_runner.js         # Automated test runner

🚀 Quick Start

Installation

# Install dependencies
npm install

# Or install AJV globally for command-line validation
npm run install-global-ajv

Basic Validation

# Validate a shot against core schema
ajv validate -s schemas/core.schema.json -d examples/simple_shot.json

# Validate whole project
ajv validate -s schemas/project.schema.json -d examples/simple_project.json

# Run all automated tests
npm test

📋 Examples

Simple Project (Minimal Fields)

{
  "projectId": "simple-dome-001",
  "title": "Simple Fulldome Experience",
  "shots": [
    {
      "schemaVersion": "1.0.0",
      "id": "sc01-ss01",
      "index": 0,
      "scene": 1,
      "durationSec": 15,
      "voice": { "lang": "en", "text": "Welcome to the universe" },
      "screenZone": "full_dome",
      "primaryTechnique": "cgi_3d_pre_render"
    }
  ]
}

Advanced Shot (All Features)

Our comprehensive examples demonstrate:

• AI-Generated Content: Using AI image/video techniques with proper copyright flagging
• Live Action: Macro photography with timelapse and proper talent releases
• Audio-Reactive: Music visualization with safety considerations for volume and seizures
• Complex Workflows: Multi-department task management and crew coordination

See the examples/ directory for complete implementations.

🎯 Available Techniques

3D & CGI

• cgi_3d_pre_render - Traditional pre-rendered 3D
• cgi_3d_realtime - Real-time 3D rendering
• volumetric_capture - Volume-based capture
• photogrammetry - 3D reconstruction from photos

2D & Graphics

• hand_drawn_2d - Traditional hand-drawn animation
• vector_2d - Vector-based graphics
• motion_graphics - Animated graphics and typography
• info_graphics - Data visualization

Simulation & Procedural

• procedural_geometry - Algorithm-generated shapes
• particle_system - Particle-based effects
• fluid_sim - Fluid dynamics simulation
• smoke_fire_sim - Volumetric effects

AI & Machine Learning

• ai_image - AI-generated imagery
• ai_video - AI-generated video
• style_transfer - AI style transformation

Live Action & Photography

• live_action_plate - Live-action footage
• macro_photography - Close-up photography
• timelapse - Time-compressed sequences
• stereo_3d_capture - Stereoscopic capture

Audio-Visual

• audio_reactive - Audio-driven visuals
• music_visualizer - Music visualization

🗺️ Screen Zones

Fulldome experiences can target specific areas of the dome:

Directional Zones

• zenith - Top of dome
• nadir - Bottom of dome (rare)
• horizon_band - Eye-level band
• upper_band / lower_band - Above/below horizon

Compass Directions

• north, south, east, west
• front, rear, left, right

Quadrants

• upper_front_left, upper_front_right
• upper_rear_left, upper_rear_right
• lower_front_left, lower_front_right
• lower_rear_left, lower_rear_right

Full Coverage

• full_dome - Entire dome surface

⚠️ Risk Flags

The schema includes comprehensive risk assessment:

Health & Safety

• photosensitive_seizure - Flashing lights concern
• motion_sickness - Camera movement issues
• vertigo_trigger - Height/movement sensitivity
• claustrophobia_trigger - Enclosed space anxiety
• loud_volume - Hearing protection needed

Technical Risks

• render_time_overrun - Computationally expensive
• hardware_overheat - System stress concerns
• sync_drift - Audio/visual synchronization
• frame_drop_risk - Performance issues

Content & Legal

• copyright_unverified - Rights clearance needed
• ai_copyright_unclear - AI-generated content concerns
• talent_release_missing - Model releases required
• mature_themes - Adult content considerations

🧪 Testing & Validation

Automated Test Suite

Run the comprehensive test suite:

npm test

This validates:

• All example files against their schemas
• Edge cases and boundary conditions
• Invalid input detection
• Enum value validation
• Required field enforcement

Manual Testing

# Test individual files
ajv validate -s schemas/core.schema.json -d test/edge_cases.json

# Test with verbose output
ajv validate -s schemas/project.schema.json -d examples/comprehensive_project.json --verbose

Test Categories

1. Validation Tests (test/validation_tests.json)

   • Minimal valid configurations
   • Invalid patterns and formats
   • Enum value testing
   • Task and people validation

2. Edge Cases (test/edge_cases.json)

   • Boundary value testing
   • Unicode content support
   • Maximum complexity scenarios
   • Error condition validation

👥 Team Roles

The schema supports comprehensive crew management:

Creative Roles

• Director, Producer, Writer
• StoryboardArtist, ConceptArtist

Technical Roles

• VFXSupervisor, CGSupervisor, PipelineTD
• Modeler, TextureArtist, Rigger, Animator
• LightingTD, Compositor, TouchDesignerDeveloper

Audio Roles

• Composer, SoundFXDesigner, AudioEngineer, VOActor

Post Production

• Editor, Colorist, QA

Custom Roles

Use "role": "other" with "customRole": "Your Custom Title" for specialized positions.

🛠️ Software Pipeline

Track software usage across the project:

3D & Animation

• Houdini, Blender, Maya, Cinema4D

Real-time Engines

• Unreal, Unity, Notch, TouchDesigner

Compositing & Editing

• AfterEffects, Nuke, DaVinciResolve

Rendering

• Redshift, Octane, Arnold, VRay

AI Tools

• StableDiffusion, Midjourney, RunwayGen2, Veo

Audio

• Ableton, ProTools, Reaper

Project Management

• ShotGrid, FTrack, git

📖 Contributing

1. Schema Changes: Bump schemaVersion (SemVer) for any breaking changes
2. Documentation: Update CHANGELOG.md for all modifications
3. Testing: Run npm test before submitting changes
4. Examples: Add examples for new features or use cases
5. Pull Requests: All changes require peer review

Development Workflow

# Install dependencies
npm install

# Run tests during development
npm test

# Validate specific examples
npm run validate-shot examples/ai_generated_shot.json
npm run validate-project examples/comprehensive_project.json

📄 License

MIT License - see LICENSE file for details.

---