Data Modeling Guide

Overview

What is charged. A new component or cluster is 100 credits when it is created; a model is 500 credits when it is created from the Model Wizard or the New Model form; Download App is 1,500 credits the first time per model, free after. Editing, publishing, generating the package and reusing components are free. See Wallet and Billing.

Data modeling in SDCStudio involves creating, customizing, and managing SDC4-compliant data structures. Whether you're refining an AI-generated model or creating one from scratch, this guide covers everything you need to know.

Understanding Data Models

Model Structure

Data Model
└── Data Cluster
    ├── Component 1 (XdString)
    ├── Component 2 (XdCount)
    ├── Component 3 (XdTemporal)
    ├── Component 4 (XdString)
    └── Component 5 (XdBoolean)

Sovereign Identity & Source Provenance

Every Data Model is automatically assigned a mandatory CUID2 instance_id, a sovereign identifier that is decoupled from any storage or transport mechanism. This ID is auto-generated and read-only.

When ingesting data from an external source system (e.g., Epic, SAP), you can optionally record:

Source Instance ID: The identifier of the Governed Data Record in the originating system
Source Version ID: The version identifier from the originating system

These fields enable auditable data lineage across system boundaries without conflating the SDC identity with the legacy source identity.

Data Model: Top-level container for your entire data structure Data Cluster: Logical grouping of related components Components: Individual data elements (fields/columns)

Component Types

SDCStudio supports all SDC4 data types:

Primitive Types: - XdString: Text data with validation - XdCount: Integer values - XdQuantity: Decimal numbers with units - XdBoolean: True/false values - XdTemporal: Dates, times, durations - XdFloat/XdDouble: Floating-point numbers

Other Types: - XdOrdinal, XdLink, XdFile, XdToken, XdInterval: Ordered symbols, links, file attachments, tokens, intervals - Lists: The eight list types (Boolean, String, Token, Decimal, Double, Integer, Non-Negative Integer, Positive Integer) - Units, Reference Ranges, Simple Reference Ranges: Supporting components for quantified types - Clusters: Grouped components - Party, Audit, Attestation, Participation: Provenance and governance components

See the SDC4 Type Reference for every type.

Working with AI-Generated Models

Reviewing Generated Models

After uploading a file, SDCStudio automatically creates:

Data Model: Named after your file (e.g., customers)
Data Cluster: Groups all columns (e.g., customers_cluster)
Components: One per column with appropriate types

Example (from CSV with columns: id, name, email, signup_date):

Data Model: customers
└── Cluster: customers_cluster
    ├── XdCount: customer_id
    ├── XdString: name
    ├── XdString: email
    └── XdTemporal: signup_date

Navigating Your Model

Navigate to Models: Go to /app/models, or use the Recent Models list on the dashboard
Find Your Model in the list (you can filter by project and status)
Click the Model Title to view details
See:
Model metadata (title, description, project, status, instance ID)
A graph of the data cluster and its components at the bottom of the page

Quick Review Checklist

✅ Verify Component Types: Are all types correct? ✅ Check Labels: Are names user-friendly? ✅ Review Validation: Are constraints appropriate? ✅ Test Required Fields: Should any be optional? ✅ Check Documentation: Are descriptions clear?

Editing Components

Access Component Editor

Navigate to Components: Go to /app/components
Find the Component you want to edit
Use the search box to filter by name
Use dropdowns to filter by type, project, status, or revision
Click the Component to view its detail page
Click the "Edit" button to open the stepped edit form (only visible if component is unpublished)

Stepped Edit Form

The component editor uses a wizard-style stepped layout with 5 steps (or 4 for the structural types that do not extend XdAny: Cluster, Party, Participation, Audit, Attestation and Reference Range):

Basic Information: Project, label, description, language, public flag
Constraints (for example String Constraints, Count Constraints, Temporal Configuration): Type-specific fields
Advanced Settings (types that extend XdAny, which includes Units and Simple Reference Range): Sequence Number, Hard Validate, UI Type, Access Control Tag (ACT), and the Require/Allow flags for VTB, VTE, TR, MOD and Location
Semantic Linking: Select RDF Objects to link semantic meaning
Review & Save: Summary of all fields with Save and Save & Publish buttons (when you create a component the button is always shown, and the server refuses it unless you may publish in the project: the project owner, team admins and staff; when you edit one, it is shown only to them)

Navigation: In edit mode, all steps are accessible - click any step in the stepper to jump directly to it. You don't need to follow the steps in order.

Component Properties

Every component has these core properties:

Basic Information

Label: - Human-readable name - Displayed in forms and documentation - Example: "Customer Email Address"

Component ID: - A CUID2 identifier generated by SDCStudio, shown on the detail page - Used in every generated artifact (mc-<id> in the XSD) - Cannot be changed

Description: - Detailed explanation of purpose - Usage guidelines - Business context

Data Type Configuration

XdString (String Constraints):

Minimum Length: 1
Maximum Length: 255
Exact Length: (optional, instead of min/max)
Format Pattern (Regular Expression): [A-Za-z ]+  (letters and spaces only)
Enumerated Values: (optional, instead of a pattern)
Default Value: (optional)

XdCount (Count Constraints):

Default Value: 0
Minimum Magnitude: 0
Maximum Magnitude: 999999
Specific Boundary Values: (optional, instead of min/max magnitude) Minimum (Inclusive), Maximum (Inclusive), Minimum (Exclusive), Maximum (Exclusive)
Total Digits: (optional)
Magnitude Status, Error Margins, Accuracy: Allow or Require flags
Units: required (select existing Units or Create new Units)
Reference Ranges: (optional) Simple Reference Range, Reference Ranges (Multiple), Normal Status

XdQuantity (Quantity Constraints):

Default Value: 0.0
Minimum Magnitude: 0.0
Maximum Magnitude: 999999.99
Specific Boundary Values, Total Digits, Fraction Digits: (optional)
Magnitude Status, Error Margins, Accuracy: Allow or Require flags
Units: required (kg, m, etc.)
Reference Ranges: (optional)

XdTemporal (Temporal Configuration):

Complete Date/Time: Allow Date-Time (YYYY-MM-DDTHH:mm:ss), Allow Date (YYYY-MM-DD),
                    Allow Time (HH:mm:ss), Allow Duration (P1Y2M3DT4H5M6S)
Partial Dates:      Allow Year (YYYY), Allow Year-Month (YYYY-MM), Allow Month (--MM),
                    Allow Month-Day (--MM-DD), Allow Day (---DD)

At least one representation must be allowed. A temporal component has no default value and no range constraint.

XdBoolean (Boolean Values):

True Value Representations (required, one per line): Yes, True, 1
False Value Representations (required, one per line): No, False, 0
Default Value: (optional, one of the representations)

The preferred control (input, dropdown, radio group, checkbox) is the UI Type in Advanced Settings.

Validation Rules

Pattern Validation (for XdString): - Regular expression patterns (must follow XML Schema regex rules) - Use the XML Regex Reference & Sandbox to browse common patterns and test your own - Common patterns: - Email: ^[^@]+@[^@]+\.[^@]+$ - Phone: ^\+?[1-9]\d{1,14}$ - Zip: ^\d{5}(-\d{4})?$ - URL: ^https?://.*

AI-Assisted Regex Generation (XdString only):

The Format Pattern (Regular Expression) field of the String form (the edit form, and the form that Quick Create opens) includes a wand button that asks the LLM to suggest an XML Schema regex. The Component Wizard's String Constraints step does not have it. The suggestion is based on the component's label, description, and any format: examples you include in the description.

To get the best results: - Use a descriptive label (e.g., "US Phone Number" rather than "phone") - Add format: examples in the description field, for example format: (555) 123-4567, 555-123-4567 - The wand button is only active when a label has been entered, the Format Pattern field is empty and no Enumerated Values are present

The generated pattern follows XML Schema regex rules (no anchors, no lookahead, max 60 characters). You can always edit the suggestion afterward. Use the XML Regex Reference & Sandbox to test and validate patterns before saving.

Note: Google Cloud Vertex AI enforces safety filters that may truncate suggestions for PII-related fields (SSN, credit card, passport, etc.). SDCStudio sanitizes known PII terms automatically, but if you get a truncated regex, use a generic label or write the pattern manually. The AI Processing Guide says which model SDCStudio calls.

Enumerated Values (allowed values), one per line:

active
inactive
pending

Enumeration Descriptions and Enumeration Definitions (URIs) are optional and take one line per value, in the same order. A format pattern cannot be combined with enumerated values, and a Default Value is ignored when enumerations are used.

Range Constraints: - Minimum and maximum magnitude, or the inclusive and exclusive boundary values, for numeric types - Minimum, maximum or exact length for strings and tokens - Temporal types have no range constraint, only the allowed representations

Example: Editing an Email Component

Before (AI-generated):

Label: email
Type: XdString
Maximum Length: 255
Format Pattern: (none)

After (customized):

Label: Customer Email Address
Type: XdString
Minimum Length: 5
Maximum Length: 320 (RFC 5321 standard)
Format Pattern: [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}
Description: Primary contact email for customer communications

Saving Changes

Cost: nothing. Edits are free, and so is Save & Publish.

Navigate to the Review & Save step (Step 5) in the edit form
Review Your Edits: The Review step shows a summary of all field values
Choose Save Option:
"Save": Saves as draft - can still be edited later
"Save & Publish": Saves AND publishes - CANNOT be edited after this
Verify: You'll be redirected to the component detail page
Test: Validation rules work as expected

⚠️ WARNING: Once you click "Save & Publish", the component becomes permanent and cannot be edited. Only use "Save & Publish" when the component is completely finalized.

Creating Components Manually

Add a New Component

Cost: 100 credits for each new component or cluster, taken when it is created. Editing, publishing and reusing a component are free.

Navigate to Components: Go to /app/components
Click "Create Component" (or Quick Create to pick a type and jump straight to its form)
Component Wizard guides you through creation:
Step 1 - Choose Type: Select the SDC4 type (XdString for text, XdCount for integers, etc.)
Step 2 - Basic Information: Select the project first (required), then enter label, description, language and the public flag
Step 3 - the type's constraints (named for the type: String Constraints, Boolean Values, ...): Configure type-specific properties (length limits, format pattern and enumerations for XdString, magnitude range and units for XdCount, allowed representations for XdTemporal, etc.). For Cluster, Party, Participation, Audit and Attestation this step only notes that the type is configured after creation
Step 4 - Advanced Settings (Xd data types only, optional): Sequence number, hard validate, UI type, XdAny flags
Step 5 - Semantic Linking (optional): Link RDF Objects for semantic meaning
Step 6 - Review & Save: Review all settings and click "Create Component"
You'll be redirected to the new component's detail page

Component Naming Best Practices

Components have no separate technical name; the label is the name, and the component ID is generated.

Labels: - Use proper capitalization: "Customer Email" - Be user-friendly: "Email Address" not "email_addr" - Include context: "Order Total Amount" not just "Total"

Working with Clusters

Creating Clusters

Clusters group related components logically.

Example: Customer Information

Customer Cluster
├── customer_id (XdCount)
├── first_name (XdString)
├── last_name (XdString)
├── date_of_birth (XdTemporal)
├── email (XdString)
├── phone (XdString)
├── address (XdString)
├── signup_date (XdTemporal)
├── status (XdString)
└── total_purchases (XdCount)

Create a New Cluster

Cost: 100 credits when the cluster is created; a cluster is a component.

Navigate to Clusters: Go to /app/clusters
Open the Cluster Wizard with New Cluster on the Clusters list (or at /app/clusters/wizard); choosing Cluster in the Component Wizard links to it from the Cluster Configuration step (creating the cluster in the Component Wizard instead gives an empty cluster whose components you add in its edit form)
Cluster Wizard guides you through three steps:
Step 1 - Basics: Project, label, description
Step 2 - Add Components: Search and select which components belong in this cluster; every component you can see is listed, grouped into Data Types, List Types and Nested Clusters, with the project named for components from another project or a public library
Step 3 - Review & Save: Review and click "Create Cluster"

Semantic links are not part of cluster creation; add them later in the cluster's edit form.

Add Components to Cluster

You can add components to a cluster when creating the cluster (Step 2), or by editing the cluster later (unpublished clusters only):

Edit the Cluster: Navigate to the cluster's detail page and click "Edit Cluster"
Go to the Cluster Configuration step: Each component type has its own list; move items between the available and chosen lists
Navigate to Review & Save: Click "Save" to apply changes

Validation and Quality Checks

Built-in Validation

SDCStudio checks the following when you save or publish:

In the forms: - Project and label are required (the Component Wizard also limits the label to 100 characters) - XdString and XdToken: a format pattern and enumerated values cannot both be set; minimum length cannot exceed maximum length; length limits are not combined with enumerations - Numeric types: a minimum cannot exceed its maximum (magnitude, inclusive and exclusive bounds); one side cannot have both an inclusive and an exclusive bound; fraction digits cannot exceed total digits - Require/Allow pairs: a value that is required (VTB, VTE, TR, MOD, Location, Magnitude Status, Error, Accuracy) must also be allowed - XdTemporal: at least one representation must be allowed

At publish: - The schema fragment generated for the component is validated as XSD 1.1, so an invalid regular expression is refused, as is an enumeration list whose Definitions count differs from its values - A cluster cannot be published while any of its components is unpublished; the message lists them - A model cannot be published while its data cluster is unpublished - A component or model whose label or title still starts with "COPY -- " cannot be published

Where Validation Issues Appear

In the component forms: project and label are checked before you can leave Basic Information; the cross-field checks run when you click Save or Save & Publish and appear, with any error the server returns, in a banner at the top of the form
On the model page: every draft model shows a Model Not Published card and, for the project owner and admins, the Publish button; if the data cluster is not yet published, Publish fails with a message that the model's associated data is not published

There is no separate validation status panel.

Fix Common Issues

Publishing fails with a schema error: - Check the regex syntax against XML Schema rules (no anchors, no lookahead) - Test the pattern with the XML Regex Reference & Sandbox - Use a simpler pattern if complex

"Minimum length cannot be greater than maximum length" (and the numeric equivalents): - Adjust range constraints - Ensure Min <= Max

Publishing Models

⚠️ CRITICAL: Publication is a ONE-TIME, Irreversible Operation

Once a component or model is published, it CANNOT be: - Edited - Unpublished - Modified - Deleted (in normal user operations)

This is a core SDC principle ensuring data model integrity and reproducibility.

When to Publish

Publish your model ONLY when: - ✅ All components are completely finalized - ✅ No errors in validation check - ✅ All required components added and tested - ✅ Validation rules thoroughly tested - ✅ Documentation complete and reviewed - ✅ Stakeholders have approved the model - ✅ You are CERTAIN this is the final version

Consider creating a test model first to validate your approach before publishing the production version.

Publish Process

Cost: nothing. Publishing is free, and so is generating the package.

IMPORTANT: You must publish child components BEFORE publishing the parent model.

Publish All Child Components First:
Navigate to each component used in your model
Review and verify each component is correct
Click "Save & Publish" for each component
Ensure ALL child components show "Published" status before proceeding
Publish the Data Model:
Navigate to Models: Go to /app/models
Find Your Model in the list
Click the Model to view details
Final Review: Verify ALL components are published and settings are correct
Click the "Publish" button on the model detail page
- This can only be done ONCE
- The button will disappear after publishing
Generate Package: After publishing the model, click Generate in the Model Generation card
This generates ALL export files (XSD, XML, JSON, JSON-LD, RDF, SHACL, GQL, HTML) in one package
This can also only be done ONCE

Status Changes: DRAFT → PUBLISHED (permanent)

⚠️ Critical Workflow: Child components → Model → Package generation. You cannot publish a model if its child components are not yet published.

What Publishing Enables

Once published and generated, you can: - ✅ Click Download Complete Package (ZIP) for the XSD, the XML and JSON Governed Data Record templates, JSON-LD, RDF (Turtle and RDF/XML), SHACL, GQL and HTML documentation - ✅ Generate and download a Lightweight or Enterprise application - ✅ Share the schema by its public URL https://sdcstudio.axius-sdc.com/dmlib/dm-<ct_id>.xsd - ✅ Share generated files with team members

What You CANNOT Do After Publishing

After publishing, you CANNOT: - ❌ Edit the model or any of its components - ❌ Unpublish the model - ❌ Delete the model (through normal UI) - ❌ Regenerate the export package - ❌ Modify any component definitions

You CAN Retire a published model or component (project owner, team admins or staff; a reason is required). It stays published, valid and resolvable by its identifier, and is no longer listed.

If You Need to Make Changes

If you discover issues after publishing:

Copy the published model or component: the detail page's Copy button creates an unpublished copy titled "COPY -- ..." in the project you choose, with lineage back to the source (Copy is offered only on published items, and copying a retired source is refused)
Rename and edit the copy
Test thoroughly before publishing it
Publish the copy when ready, and Retire the original if it should no longer be offered

SDCStudio does not keep versions of a published model. Use the title to tell successors apart (for example "CustomerModel 2") and document what changed in the description.

Best Practices

Design Principles

Keep It Simple: - Start with core components - Add complexity gradually - Don't over-engineer initial models

Be Consistent: - Use consistent naming conventions - Apply similar validation rules to similar fields - Maintain logical grouping in clusters

Document Everything: - Add clear descriptions to all components - Explain validation rules - Document business logic

Think Long-Term: - Design for reusability - Consider future extensions - Plan for data evolution

Component Organization

Logical Grouping: - Group related components in a cluster - Keep clusters flat where you can; nested clusters are allowed but harder to read - Use meaningful cluster names

Example: E-commerce Order

Order Model
└── Order Data Cluster
    ├── order_id
    ├── order_date
    ├── order_status
    ├── customer_id
    ├── customer_email
    ├── shipping_address
    ├── shipping_method
    ├── tracking_number
    ├── payment_method
    ├── total_amount
    └── payment_status

Validation Strategy

Balance Strictness: - Too strict: Users can't enter valid data - Too loose: Invalid data gets through - Find the right balance for your use case

Common Sense Validation: - Email: Pattern match + max length - Phone: Pattern match + min/max length - Dates: Reasonable range (not year 1000) - Quantities: Non-negative (unless negatives valid)

Test Your Validation: - Try valid edge cases - Try invalid inputs - Verify error messages make sense

Advanced Features

Semantic Definitions

Link your components to ontologies for better AI understanding:

Edit Component and navigate to the Semantic Linking step
Add Semantic Link:
Move existing RDF Objects from Available RDF Objects to Selected RDF Objects
Or create a new one with the Create new RDF Object button (a project must be selected first)
Use the Search Google for controlled vocabularies button to look up terms; it opens a Google search pre-configured with ontology-focused sources (OBO Foundry, BioPortal, LOV, etc.)
Save: Component now has semantic meaning

See Semantic Enhancement Guide for details.

Reusing Components

Published components can be added to any number of clusters and models in their project, and in any project when they are public
Copy on a component's detail page makes an unpublished copy you can adapt; the copy records where it came from

Troubleshooting

Can't Save Component

Validation Errors: - Check all required fields filled - Verify regex pattern syntax - Ensure min <= max for ranges - Check the Require/Allow flags (a required value must also be allowed)

Permission Issues: - Verify your role: the project owner, team admins and staff edit and publish; a team member edits drafts but cannot publish - Published components cannot be edited: the Edit button is not shown; use Copy instead - Save & Publish succeeds only for the project owner, team admins and staff (on a create form it is shown to everyone and refused for anyone else)

Component Not Appearing

Cache Issues: - Refresh the page - Clear browser cache - Try different browser

List Issues: - Click Clear All Filters on the Components page; a type, project, status or revision filter may be hiding it - Retired components are hidden unless the status filter is set to Retired; they remain reachable by their URL - Verify the component saved successfully (you are redirected to its detail page)

Validation Fails

Review Error Messages: - Read validation errors carefully - Fix one error at a time - Re-validate after each fix

Common Fixes: - Fix regex pattern syntax - Adjust range constraints - Complete required fields

Next Steps

Semantic Enhancement - Add ontologies for better AI
Generating Outputs - Create schemas and apps
AI Processing Guide - Understand AI analysis
SDC4 Type Reference - Complete type documentation

Getting Help

Troubleshooting Guide - Common issues
Support: contact@axius-sdc.com

Ready to build? Start creating and customizing your data models today.