XML Instance Generation Guide

Overview

When you generate the package for a published data model, SDCStudio produces a Governed Data Record template in XML (dm-<ct_id>.xml) shaped by the model's XSD schema. Generation is schema-aware: the file contains the elements your data model's schema declares, not the whole SDC4 reference model, and every data value is a placeholder (_PH_ where the element is required, _OPT_PH_ where it is optional) that you replace with real data.

IMPORTANT: XML instance generation is a ONE-TIME operation. It happens as part of the complete package generation after a model is published, and the file cannot be regenerated. Make sure the model is complete and correct before you click Generate.

Key Characteristics

Schema-Aware Generation

  • Only elements declared in your data model's schema appear in the file
  • The result is a clean template that validates against your schema once the placeholders are replaced

DMType Elements

  • The metadata elements of the model (label, language, encoding, timestamp, version, instance ID) are included
  • They precede the main data cluster

Component-Level Accuracy

  • Each component's schema is parsed to find the elements it defines
  • Nothing is assumed beyond what the schema says
  • The generated XML is checked for well-formedness; it validates against the schema once the placeholders are replaced

How It Works

1. Schema Analysis

The generator parses your data model's XSD schema to find: - Which DMType elements are defined - Which components are included - Which elements each component supports - The constraints that apply

2. Element Discovery

For each component, the generator: - Reads the complexType definition - Extracts element names and types - Follows nested elements and references - Notes which elements are required and which carry a fixed value

3. XML Generation

From the discovered schema it: - Writes the DMType metadata elements - Builds each component with its wrapper elements - Pre-fills the fixed values (labels, language, encoding, a link's relation, an ordinal's first state, a boolean's first true value) and marks every other value _PH_ or _OPT_PH_ - Produces well-formed XML; the JSON instance in the same package carries sample values instead

Generated XML Structure

DMType Elements (Schema-Defined)

<?xml version="1.0" encoding="UTF-8"?>
<sdc4:dm-{model-id}
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sdc4="https://semanticdatacharter.com/ns/sdc4/"
  xsi:schemaLocation="https://semanticdatacharter.com/ns/sdc4/ https://semanticdatacharter.com/dmlib/dm-{model-id}.xsd">
  <!-- 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>_PH_</creation_timestamp>
  <instance_id>{the model's Instance ID}</instance_id>
  <instance_version>_PH_</instance_version>
  <source_instance_id>_OPT_PH_</source_instance_id>
  <source_version_id>_OPT_PH_</source_version_id>
  <current-state>_OPT_PH_</current-state>

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

The root element is sdc4:dm-<ct_id> and its xsi:schemaLocation names the model's schema, so the record is self-describing. The instance_id is the model's own Instance ID; current-state carries the model's state when one was set.

Component Elements (Schema-Defined)

<!-- Only elements defined in your component schema, in schema order -->
<sdc4:ms-{adapter-id}>
  <sdc4:ms-{component-id}>
    <label>Component Label</label>
    <vtb>_OPT_PH_</vtb>
    <vte>_OPT_PH_</vte>
    <tr>_OPT_PH_</tr>
    <modified>_OPT_PH_</modified>
    <latitude>_OPT_PH_</latitude>
    <longitude>_OPT_PH_</longitude>
    <xdstring-value>_PH_</xdstring-value>
  </sdc4:ms-{component-id}>
</sdc4:ms-{adapter-id}>

A component placed in a cluster is wrapped twice: the outer ms- element is the adapter the cluster's schema declares for that position, the inner one is the component itself. An element made required in Advanced Settings (for example Require VTB) carries _PH_ instead of _OPT_PH_.

The XML and JSON files in the package are the same Governed Data Record in two serializations. XML (W3C XSD 1.1) is the canonical form.

What Gets Generated

Always Included

  • Root Element: sdc4:dm-<ct_id> with the namespace declarations and xsi:schemaLocation
  • DMType Elements: Those defined in your schema
  • Data Cluster: The main data structure wrapper, with its label
  • Component Wrappers: The adapter element and the ms-<component id> element for each component in a cluster

Conditionally Included

  • Component Elements: Only if defined in the component schema; optional ones (act, vtb, vte, tr, modified, latitude, longitude, magnitude status, accuracy margin and the like) carry _OPT_PH_
  • Nested Elements: Discovered through schema parsing (units, interval bounds, list values)
  • Subject, provider and governance slots: Only when the model populates them

Never Generated

  • ExceptionalValue: an abstract slot; the validator inserts one only when real data fails
  • The generic ReferenceRange slot: a model-defined reference range is emitted as its own component instead
  • Anything not found in the schema

Benefits of Schema-Aware Generation

For Application Developers

  • Accurate Templates: the XML matches your exact schema
  • No Surprises: only expected elements are present
  • Validation Ready: the file passes schema validation once the placeholders are replaced
  • Marked Values: every place that needs data is marked, and the JSON instance shows sample values of the right shape

For Data Modelers

  • Schema Check: a quick way to see what the schema actually defines
  • Testing: realistic examples for testing data structures
  • Documentation: examples for stakeholders
  • Compliance: SDC4 conformance of the record

For System Integration

  • API Testing: use the generated XML in API tests
  • Pipeline Validation: verify data processing pipelines
  • Tool Integration: test external tools and validators
  • Training: examples for team members

Usage Examples

Generate the XML Instance

  1. Navigate to Models: go to /app/models
  2. Click on your published data model
  3. In the Model Generation card click Generate
  4. This generates ALL export files (XSD, XML, JSON, JSON-LD, RDF, SHACL, GQL, HTML)
  5. This can only be done ONCE; regeneration is not possible
  6. Click Download Complete Package (ZIP) and open dm-<ct_id>.xml

For a published model in a public project the same file is also served by the catalog API at https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/<ct_id>/xml/.

Use the File as a Template

The values are placeholders: replace every _PH_ with real data, replace or remove each _OPT_PH_ element, keep the fixed values and the element structure, and validate the result against dm-<ct_id>.xsd (the README-AI-PROMPT.md in the package describes the placeholder convention). The open-source sdcvalidator package validates with XSD 1.1 and separates structural errors from semantic ones:

pip install sdcvalidator
sdcvalidate dm-<ct_id>.xsd my-record.xml

The exit code is 0 when the record is valid, 1 for semantic errors only, 2 for structural errors.

Troubleshooting

Common Issues

No Generate Button

  • Check: the model must be published; a draft shows Publish, Edit or Delete instead, according to your role
  • Check: every child component must be published before Publish succeeds; otherwise the model is not published and the message says its associated data is not published

Generation Fails

  • Reload the model page; if Generate is still shown, click it again
  • Still failing: contact contact@axius-sdc.com with the model's ct_id

Missing Elements

  • Verify: the element is defined in the component (the XML only reflects the schema)
  • Review: the component's constraints and the cluster membership
  • A published model cannot be changed; Copy it, fix the copy, publish and generate again

Validation Errors

  • The unedited template does not validate: _PH_ and _OPT_PH_ are markers, not values
  • Validate with an XSD 1.1 processor; XSD 1.0 validators report errors on SDC4 schemas
  • Check that the replaced values satisfy the component constraints (length, pattern, magnitude, allowed temporal formats)

Best Practices

For Optimal XML Generation

Data Model Design

  • Complete Components: define all the constraints you need before publishing
  • Clear Relationships: put components in the right clusters
  • Documentation: add clear labels and descriptions; both appear in the generated files

Component Organization

  • Logical Grouping: organize components in meaningful clusters
  • Consistent Naming: use clear, descriptive labels
  • Proper Types: choose the SDC4 data type that matches the data
  • Reusable Components: published components can be used in more than one model

Schema Quality

  • SDC4 Conformance: follow the Semantic Data Charter modeling rules
  • Constraint Testing: test patterns with the XML Regex Reference & Sandbox before publishing
  • Cross-References: verify units and reference ranges are attached where needed

Need Help? Check the Troubleshooting Guide for common issues, or the Data Modeling Guide for building models that produce useful templates.