Module schema

ddex_builder

Module schema 

Source
Expand description

§JSON Schema Generation for DDEX Models

This module provides comprehensive JSON Schema generation from DDEX structures for validation, documentation, and cross-language type definitions. It supports version-specific variations, profile-based constraints, partner preset rules, and can generate TypeScript and Python type definitions.

§Key Features

  • JSON Schema Draft 2020-12 and Draft-07 support for broad compatibility
  • DDEX Version Aware: Generates schemas for ERN 3.8.2, 4.2, and 4.3
  • Message Profile Support: Audio, Video, and Mixed content profiles
  • Partner Preset Integration: Incorporates partner-specific validation rules
  • Multi-Language Export: TypeScript .d.ts and Python TypedDict generation
  • Advanced Validation: Pattern matching, conditional schemas, enum constraints

§Architecture Overview

Schema Generation Pipeline
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ DDEX Structures │───▶│ SchemaGenerator  │───▶│  JSON Schema    │
│ (Rust types)    │    │                  │    │ (Draft 2020-12) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
          │                       │                       │
          ▼                       ▼                       ▼
   ┌─────────────┐      ┌─────────────────┐    ┌─────────────────┐
   │ • BuildReq  │      │ • Version Rules │    │ • Validation    │
   │ • Releases  │      │ • Profile Cnstr │    │ • Documentation │
   │ • Tracks    │      │ • Partner Rules │    │ • Type Export   │
   │ • Metadata  │      │ • Type Mapping  │    │ • References    │
   └─────────────┘      └─────────────────┘    └─────────────────┘

§Generation Capabilities

§Core Schema Types

  • BuildRequest: Complete DDEX build request structure
  • FlatRelease: Simplified release representation
  • Complete Schema: All DDEX types with cross-references

§Output Formats

  • JSON Schema: Standards-compliant validation schemas
  • TypeScript: .d.ts type definition files
  • Python: TypedDict class definitions

§Usage Examples

§Basic Schema Generation

use ddex_builder::schema::{SchemaGenerator, SchemaConfig};
use ddex_builder::presets::{DdexVersion, MessageProfile};

let generator = SchemaGenerator::new(
    DdexVersion::Ern43,
    MessageProfile::AudioAlbum
);

let result = generator.generate_build_request_schema()?;
let schema_json = serde_json::to_string_pretty(&result.schema)?;
println!("Generated schema:\n{}", schema_json);

§Advanced Configuration

use ddex_builder::schema::*;
use ddex_builder::presets::*;

let config = SchemaConfig {
    draft_version: SchemaDraft::Draft202012,
    include_examples: true,
    include_descriptions: true,
    strict_validation: true,
    version_conditionals: true,
    ..Default::default()
};

let spotify_preset = spotify_audio_43();
let generator = SchemaGenerator::with_preset(
    DdexVersion::Ern43,
    MessageProfile::AudioAlbum,
    spotify_preset
).with_config(config);

let result = generator.generate_complete_schema()?;

§Type Definition Export

// Generate TypeScript definitions
let typescript = generator.generate_typescript_types(&result.schema)?;
std::fs::write("ddex-types.d.ts", typescript)?;

// Generate Python definitions
let python = generator.generate_python_types(&result.schema)?;
std::fs::write("ddex_types.py", python)?;

§Schema Features

§Validation Rules

  • Required Fields: Platform-specific mandatory fields
  • Format Validation: ISRC, UPC, date format validation
  • Pattern Matching: Regex patterns for code validation
  • Enum Constraints: Allowed values for controlled vocabularies
  • Conditional Logic: Version-specific field requirements

§Documentation Integration

  • DDEX Specification: Field descriptions from official docs
  • Examples: Real-world usage examples for each field
  • Cross-References: Links between related schema definitions
  • Version Notes: Migration guidance between DDEX versions

§Performance Characteristics

  • Schema Generation: 1-5ms for complete schema generation
  • Type Export: 5-15ms for TypeScript/Python generation
  • Memory Usage: ~2MB peak for complete schema with examples
  • Cache Support: Generated schemas are reusable across builds

§Command Line Interface

The schema generator includes CLI support:

# Generate complete schema
ddex-builder schema --version 4.3 --profile AudioAlbum --output schema.json

# Include TypeScript and Python types
ddex-builder schema --version 4.3 --profile AudioAlbum \
  --typescript --python --examples --strict

Structs§

JsonSchema
Complete JSON Schema representation
SchemaCommand
Generate schema command-line arguments
SchemaConfig
Configuration for schema generation
SchemaGenerationResult
Schema generation result with metadata
SchemaGenerator
Main JSON Schema generator for DDEX models
SchemaMetadata
Metadata about generated schema
SchemaValidationConfig
Configuration for schema validation
SchemaValidationResult
Result of schema validation
SchemaValidator
Schema-based validator for DDEX data
SchemaWarning
Warning during schema generation

Enums§

SchemaDraft
Supported JSON Schema draft versions