XML Instance Generation Guide

Overview

The XML Instance Generator creates example XML documents that conform to your data model's XSD schema. Unlike previous versions, the current system is schema-aware, meaning it only generates elements that are actually defined in your data model schema, not optional elements from the reference model.

IMPORTANT: XML instance generation is a ONE-TIME operation that occurs as part of the complete package generation after publishing a model. Once generated, the XML instance cannot be regenerated. Ensure your model is complete and correct before generating.

Key Improvements

Schema-Aware Generation

Before: Generated unnecessary optional elements that weren't in your schema
After: Only generates elements explicitly defined in your data model
Benefit: Cleaner, more accurate XML instances that serve as proper templates

DMType Elements

Automatic Inclusion: Required metadata elements are automatically added
Schema-Based: Only includes DMType elements defined in your schema
Proper Ordering: DMType elements precede the main data cluster

Component-Level Accuracy

Element Discovery: Parses component schemas to find defined elements
No Hardcoded Elements: Removes assumptions about what should be included
Validation Ready: Generated XML validates against your schema

How It Works

1. Schema Analysis

The generator parses your data model's XSD schema to understand: - Which DMType elements are defined - What components are included - Which elements each component supports - Validation rules and constraints

2. Element Discovery

For each component, the system: - Searches for complexType definitions - Extracts element names and types - Identifies nested elements and references - Maps SDC4 types to appropriate values

3. XML Generation

Based on the discovered schema: - Generates DMType metadata elements - Creates component structures with proper wrappers - Applies validation rules and constraints - Produces well-formed, schema-compliant XML

Generated XML Structure

DMType Elements (Schema-Defined)

<?xml version="1.0" encoding="UTF-8"?>
<dm-{model-id} xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/">
  <!-- Only DMType elements defined in your schema -->
  <dm-label>Your Model Title</dm-label>
  <dm-language>en-US</dm-language>
  <dm-encoding>utf-8</dm-encoding>
  <creation_timestamp>2025-08-31T15:42:25.359348</creation_timestamp>
  <instance_version>1.0</instance_version>
  <current-state></current-state>
  <instance_id>dm-{model-id}</instance_id>

  <!-- Main data cluster -->
  <sdc4:ms-{cluster-id}>
    <!-- Component content -->
  </sdc4:ms-{cluster-id}>
</dm-{model-id}>

Component Elements (Schema-Defined)

<!-- Only elements defined in your component schema -->
<mc-{component-id}>
  <label>Component Label</label>
  <xdstring-value>Sample Data</xdstring-value>
  <!-- Other elements as defined in schema -->
</mc-{component-id}>

What Gets Generated

Always Included

Root Element: With proper namespace declarations
DMType Elements: Only those defined in your schema
Data Cluster: Main data structure wrapper
Component Wrappers: XdAdapter wrappers for components

Conditionally Included

Component Elements: Only if defined in component schema
Validation Rules: Applied based on schema constraints
Nested Elements: Discovered through schema parsing
Reference Elements: If referenced in schema

Never Generated (Unless in Schema)

Optional SDC4 Elements: ReferenceRange, accuracy_margin, etc.
Generic Elements: Latitude, longitude, vtb, vte, etc.
Hardcoded Elements: Elements not discovered in schema parsing

Benefits of Schema-Aware Generation

For Application Developers

Accurate Templates: XML instances match your exact schema
No Surprises: Only expected elements are present
Validation Ready: Generated XML passes schema validation
Proper Examples: Real-world usage examples

For Data Modelers

Schema Validation: Verify your schema is complete and correct
Testing: Test data structures with realistic examples
Documentation: Generate examples for stakeholders
Compliance: Ensure SDC4 compliance

For System Integration

API Testing: Use generated XML for API testing
Data Validation: Verify data processing pipelines
Tool Integration: Test external tools and validators
Training: Provide examples for team members

Usage Examples

Generate XML Instance

Via Web Interface (React UI): 1. Navigate to Models: Go to /app/models 2. Click on your published data model 3. Generate Package (One-Time Only): - If not yet generated, you'll see the "Generate Package (One-Time Only)" button - Click this button to generate ALL export files (XSD, XML, JSON, HTML, etc.) - This can only be done ONCE - regeneration is not allowed 4. Download the XML instance using the "XML Instance" download button

Via Django Management Command (Admin/Testing Only):

python manage.py generate_xml {model-id} --force

Note: The Django management command is primarily for administrative/testing purposes. Normal users should use the web interface for one-time generation.

Troubleshooting

Common Issues

XML Generation Fails

Check: Ensure your data model is published
Verify: XSD schema generation completed successfully
Review: Check for validation errors in your model

Missing Elements

Verify: Elements are defined in your component schemas
Check: Schema parsing completed successfully
Review: Component definitions and relationships

Validation Errors

Schema: Ensure XSD schema is valid
Components: Check component definitions
Constraints: Verify validation rules are correct

Debug Information

The generator provides detailed logging: - Schema Parsing: Shows discovered elements - Component Processing: Tracks component generation - Element Discovery: Lists found elements for each component - Generation Status: Progress and completion information

Best Practices

For Optimal XML Generation

Data Model Design

Complete Schemas: Define all required elements in your schema
Clear Relationships: Establish proper component relationships
Validation Rules: Include appropriate constraints and rules
Documentation: Add clear labels and descriptions

Component Organization

Logical Grouping: Organize components in meaningful clusters
Consistent Naming: Use clear, descriptive names
Proper Types: Choose appropriate SDC4 data types
Reusable Components: Create components that can be shared

Schema Quality

SDC4 Compliance: Follow SDC4 modeling standards
Element Completeness: Include all necessary metadata
Constraint Validation: Test validation rules thoroughly
Cross-References: Verify component relationships

Advanced Features

Custom Element Generation

Template System: Customize element content generation
Data Patterns: Apply realistic data patterns
Business Rules: Implement domain-specific logic
External Data: Integrate with external data sources

Validation Integration

Schema Validation: Automatic validation against XSD
Business Rule Validation: Custom validation logic
Data Quality Checks: Verify data integrity
Compliance Checking: Ensure regulatory compliance

Future Enhancements

Planned Improvements

Enhanced Data Generation: More sophisticated sample data
Template Customization: User-defined generation templates
Batch Generation: Generate multiple instances at once
Export Formats: Additional output formats (JSON, YAML)

Integration Features

API Integration: Generate XML via REST API
Webhook Support: Trigger generation on model changes
Scheduled Generation: Automatic periodic generation
Version Control: Track changes in generated instances

Need Help? Check the Troubleshooting Guide for common issues, or explore the Data Modeling Guide for best practices in creating models that generate high-quality XML instances.