Generating Outputs Guide

Overview

Once your data model is published, SDCStudio can generate various outputs: XSD schemas, XML instances, JSON schemas, HTML forms, and complete web applications. This guide covers all generation capabilities.

Prerequisites

Before generating outputs: - ✅ Data model created and validated - ✅ All components configured and finalized - ✅ Model published (ONE-TIME operation - cannot be unpublished) - ✅ No validation errors

IMPORTANT: Publication and generation are ONE-TIME, irreversible operations. Once a model is published and its package is generated, it CANNOT be edited, regenerated, or unpublished. Ensure your model is complete and correct before publishing.

XSD Schema Generation

What is XSD?

XSD (XML Schema Definition) is a W3C standard for defining XML document structure. SDCStudio generates SDC4-compliant XSD schemas from your data models.

Generate XSD

Navigate to Models: Go to /app/models
Find Your Published Model: Click on the model to view its detail page
Generate Package (One-Time Only):
If not yet generated, click the "Generate Package (One-Time Only)" button
This generates ALL export files (XSD, XML, JSON, HTML, etc.) in a single operation
This can only be done ONCE - regeneration is not allowed
Download XSD: Click the "XSD Schema" button to download the generated XSD file

Note: XSD is part of the complete package generated once after publication. Individual files cannot be generated separately.

XSD Features

Full SDC4 Compliance: - All SDC4 data types supported - Proper namespace declarations - Valid XML Schema structure

Validation Rules: - Min/max constraints - Pattern validation - Required/optional fields - Enumeration values

Documentation: - Component descriptions - Usage guidelines - Validation messages

Example Output:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:sdc4="http://sdc4.org/schema"
            targetNamespace="http://example.com/customers">

  <xsd:element name="customer_email" type="mc-customer-email-type">
    <xsd:annotation>
      <xsd:documentation>Customer Email Address</xsd:documentation>
    </xsd:annotation>
  </xsd:element>

  <xsd:complexType name="mc-customer-email-type">
    <xsd:sequence>
      <xsd:element name="xdstring-value" type="sdc4:XdStringType">
        <xsd:restriction base="xsd:string">
          <xsd:minLength value="5"/>
          <xsd:maxLength value="320"/>
          <xsd:pattern value="^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"/>
        </xsd:restriction>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

XML Instance Generation

What is XML Instance?

An XML instance is an example XML document that validates against your XSD schema. It serves as a template for data entry.

Generate XML Instance

Navigate to Models: Go to /app/models
Find Your Published Model: Click on the model to view its detail page
Generate Package (One-Time Only):
If not yet generated, click the "Generate Package (One-Time Only)" button
This generates ALL export files including the XML instance
This can only be done ONCE - regeneration is not allowed
Download XML: Click the "XML Instance" button to download the generated XML file

Note: XML Instance is part of the complete package generated once after publication. It cannot be generated separately or regenerated.

Schema-Aware Generation

Key Feature: SDCStudio only generates elements defined in YOUR schema, not the entire SDC4 reference model.

Before (old behavior): - Generated all possible SDC4 elements - Included unnecessary optional elements - Large, cluttered XML files

Now (schema-aware): - Only generates YOUR defined elements - Clean, focused templates - Valid against YOUR schema

Example:

<?xml version="1.0" encoding="UTF-8"?>
<customers xmlns="http://example.com/customers"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://example.com/customers customers.xsd">

  <customer>
    <customer_id>
      <xdcount-value>1001</xdcount-value>
    </customer_id>
    <customer_email>
      <xdstring-value>jane.smith@example.com</xdstring-value>
    </customer_email>
    <signup_date>
      <xdtemporal-value>2024-01-15</xdtemporal-value>
    </signup_date>
  </customer>
</customers>

Using XML Instances

As Templates: - Copy and modify for data entry - Understand expected structure - Test validation rules

For Testing: - Validate against XSD - Test data processing pipelines - Verify transformations

For Documentation: - Show data structure - Provide examples - Training materials

JSON and JSON-LD Generation

What are JSON Outputs?

SDCStudio generates two types of JSON files that serve different purposes:

JSON Instance (dm-{id}-instance.json): - Complete data example mirroring XML structure - Includes all component values and hierarchy - Developer-friendly format for API development - Sample data with proper constraints

JSON-LD Schema (dm-{id}.jsonld): - Semantic description of the data model - Links to formal ontologies and vocabularies - Machine-readable metadata for linked data - Rich documentation and relationships

Generate JSON Outputs

JSON files are generated as part of the one-time package generation:

Navigate to Models: Go to /app/models
Find Your Published Model: Click on the model to view its detail page
Generate Package (One-Time Only):
If not yet generated, click the "Generate Package (One-Time Only)" button
This generates ALL export files including JSON Instance and JSON-LD Schema
This can only be done ONCE - regeneration is not allowed
Download: Use individual download buttons for "JSON Instance" or "JSON-LD Schema", or download the complete ZIP package

JSON Instance Features

Complete Data Structure: - Mirrors XML instance format - All components with sample values - Proper nesting and hierarchy - Constraint-aware data generation

Example JSON Instance:

{
  "@context": "https://semanticdatacharter.com/ns/sdc4/",
  "dm_id": "jsi5yxnvzsmsisgn2bvelkni",
  "dm_type": "dm-jsi5yxnvzsmsisgn2bvelkni",
  "metadata": {
    "dm_language": "en-US",
    "dm_label": "StatePopulation",
    "dm_encoding": "utf-8",
    "instance_id": "dm-jsi5yxnvzsmsisgn2bvelkni",
    "instance_version": "1.0",
    "creation_timestamp": "2025-10-17T16:33:50.115552"
  },
  "data": {
    "component_id": "wnpz4qyrk369gnsivfsmysdf",
    "label": "StatePopulation Data Cluster",
    "type": "Cluster",
    "items": [
      {
        "component_id": "cpq0lpgg887vpys05bucuep3",
        "label": "State",
        "type": "XdString",
        "value": "California"
      },
      {
        "component_id": "q1ey1sf5otsa97e76kb06hco",
        "label": "Adult Population",
        "type": "XdCount",
        "value": 29500000,
        "units": {
          "label": "Count Units",
          "value": "people"
        }
      }
    ]
  }
}

JSON-LD Schema Features

Semantic Description: - Component types and relationships - Constraints and validation rules - Ontology mappings (schema.org, SIO, etc.) - Dublin Core metadata

Example JSON-LD Schema:

{
  "@context": {
    "@vocab": "https://semanticdatacharter.com/ns/sdc4/",
    "sdc4": "https://semanticdatacharter.com/ns/sdc4/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "dc": "http://purl.org/dc/elements/1.1/"
  },
  "@type": "DataModel",
  "@id": "sdc4:dm-jsi5yxnvzsmsisgn2bvelkni",
  "label": "StatePopulation",
  "description": "Population data by state",
  "components": [
    {
      "@type": "XdStringType",
      "@id": "sdc4:mc-cpq0lpgg887vpys05bucuep3",
      "label": "State",
      "dataType": "xsd:string",
      "constraints": {
        "maxLength": 50
      }
    },
    {
      "@type": "XdCountType",
      "@id": "sdc4:mc-q1ey1sf5otsa97e76kb06hco",
      "label": "Adult Population",
      "dataType": "xsd:integer",
      "constraints": {
        "minInclusive": 0,
        "units": {
          "@type": "Units",
          "label": "people"
        }
      }
    }
  ],
  "metadata": {
    "dc:title": "StatePopulation",
    "dc:creator": "Your Name",
    "dc:language": "en-US"
  }
}

Using JSON Outputs

JSON Instance Use Cases: - API Development: REST API request/response examples - Testing: Sample data for automated tests - Documentation: Show data structure to developers - Code Generation: Generate TypeScript/JavaScript interfaces - Data Exchange: JSON alternative to XML instance

JSON-LD Schema Use Cases: - Semantic Web: Integration with linked data systems - Knowledge Graphs: Import into graph databases - Metadata Catalogs: Machine-readable schema description - Ontology Mapping: Link to formal vocabularies - RDF Processing: Convert to RDF triples

Differences from JSON Schema

Important Note: SDCStudio generates JSON instances and semantic descriptions, not JSON Schema validation files.

✅ JSON Instance: Example data (like XML instance)
✅ JSON-LD: Semantic metadata (ontology description)
❌ JSON Schema: Validation schema (not currently generated)

For validation, use the XSD schema with SDC4-compliant validators like sdcvalidator.

Application Generation

Planned Feature

Note: Application generation is currently planned for a future release and is not yet available in the React UI.

Future Capabilities

When implemented, SDCStudio will be able to generate complete, deployable web applications:

Reflex Applications (Planned): - Python-based full-stack apps - Data entry forms - Data viewing interfaces - RESTful API endpoints - Database models

HTML Forms (Planned): - Responsive web forms - Client-side validation - Accessibility features - Dark mode support

Current Alternatives

Until application generation is implemented, you can: - Export JSON schemas for use in custom applications - Download XML schemas for XML-based applications - Use generated HTML documentation as a reference for building forms manually

Planned Application Features

When application generation is implemented, generated apps will include:

Data Entry Forms: - Automatic form generation from model - Built-in validation based on constraints - User-friendly error messages - Progress indicators

Data Viewing: - Table view with sorting/filtering - Detail view for individual records - Search functionality - Pagination

Database Integration: - Automated database models - Migration support - CRUD operations - Data validation

API Endpoints: - RESTful API - JSON responses - Authentication support - Rate limiting

Export Formats

Generated Output Files

When you publish a data model, SDCStudio generates a complete package of files:

Core Files: - dm-{id}.xsd: XML Schema for validation - dm-{id}.xml: XML instance with sample data - dm-{id}-instance.json: JSON instance with complete data structure - dm-{id}.jsonld: JSON-LD semantic schema description - dm-{id}.html: Human-readable documentation

Additional Files: - dm-{id}.ttl: SHACL shapes for RDF validation - dm-{id}.rdf: Extracted RDF triples (N-Quads format) - dm-{id}.gql: GQL CREATE statements for property graphs - dm-{id}.sha1: SHA1 hash for integrity verification - {title}.zip: Complete package with all files

Download Options

Individual Files: - Download specific files from the model detail page after generation - Each file has a direct download link - Files available immediately after the one-time package generation

Complete Package: - Download ZIP containing all generated files - Includes README, SHACL documentation, and all export formats - One-click download for everything - Note: The package can only be generated once - download and save it carefully

Use Cases: - XSD: Schema validation, XML processing - XML Instance: Data entry templates, testing - JSON Instance: API development, JavaScript apps - JSON-LD: Linked data, semantic web, knowledge graphs - HTML: Documentation, training, compliance - SHACL: RDF validation, ontology work - RDF: Triple stores, graph databases - ZIP: Distribution, archival, deployment

Advanced Features

Custom Templates (Planned)

Custom template support is planned for a future release:

Future Capabilities: - Custom Jinja2 templates for code generation - Template management in Settings - Variable definition and custom logic - Template selection during generation

Batch Generation (Planned)

Batch generation is planned for a future release:

Future Capabilities: - Select multiple models for batch processing - Generate all export formats at once - Bulk download as single ZIP file - Progress tracking for multiple models

Current Batch Alternative

For now, you can: - Publish multiple models individually - Generate the package once for each published model - Download individual ZIP packages for each model

Version Control

Track schema versions:

Automatic Versioning: - Each generation creates a version - Version history maintained - Compare versions

Manual Versioning: - Tag important versions - Add version notes - Export specific versions

Best Practices

Before Generation

⚠️ CRITICAL: Publication and generation are ONE-TIME, irreversible operations

Validate Thoroughly: - Check all components are complete and correct - Test validation rules extensively - Review all documentation and labels - Verify all relationships and references - Ensure all components are published and finalized - Remember: Once published, models CANNOT be edited

Plan Usage: - Know exactly what you'll use the model for - Understand all export formats you'll need - Verify your model meets all requirements - Consider creating a test model first to validate your approach

Final Checklist Before Publishing: - [ ] All components tested and validated - [ ] All descriptions and labels are accurate - [ ] All relationships properly configured - [ ] Validation rules tested with sample data - [ ] Model reviewed by stakeholders - [ ] Certain this is the final version

After Generation

Immediately Save All Files: - Download the complete ZIP package immediately - Save individual files you need - Store in version control or backup system - Remember: You cannot regenerate these files

Test Generated Outputs: - Validate XML against XSD - Test JSON structure - Verify all export formats - Confirm all components are present

Document and Archive: - Save the complete package in a secure location - Document what the model represents - Record any important decisions made - Keep backups of all generated files

Troubleshooting

Generation Fails

Validation Errors: - Fix model validation issues - Ensure all required fields set - Check for circular dependencies

Configuration Issues: - Verify namespace settings - Check file paths - Review generation options

Invalid Output

XSD Validation Fails: - Check component types - Verify constraints - Review namespace declarations

XML Doesn't Validate: - Ensure XSD generated correctly - Check sample data - Verify element structure

Application Won't Run: - Check dependencies installed - Verify database configuration - Review error logs

Next Steps

First Data Model - Complete workflow tutorial
Data Modeling Guide - Optimize your models
Troubleshooting Guide - Common issues

Getting Help

XML Instance Generation Guide - Detailed XML guide
Developer Documentation - Technical details
Support: support@axius-sdc.com

Ready to generate? Publish your model and start creating schemas and applications!