Data Modeling Guide

Overview

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 Hierarchy

Data Model
└── Data Cluster (root)
    ├── Component 1 (XdString)
    ├── Component 2 (XdCount)
    ├── Component 3 (XdTemporal)
    └── Sub-cluster
        ├── Component 4
        └── Component 5

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

Complex Types: - Clusters: Grouped components - Lists: Ordered collections - References: Links to other components - Adapters: Special wrappers

See Data Types Reference for complete details.

Working with AI-Generated Models

Reviewing Generated Models

After uploading a file, SDCStudio automatically creates:

1. Data Model: Named after your file (e.g., customers)
2. Root Cluster: Groups all columns (e.g., customers_cluster)
3. 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

1. Navigate to Models: Go to /app/models or click "Browse Data Models" on the dashboard
2. Find Your Model in the list (you can filter by project)
3. Click the Model Name to view details
4. See:
5. Model metadata (name, description, status)
6. Root cluster structure
7. All components
8. Validation status

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

1. Navigate to Components: Go to /app/components
2. Find the Component you want to edit
3. Use the search box to filter by name
4. Use dropdowns to filter by type, project, or status
5. Click the Component to view its detail page
6. Click the "Edit" button to open the editor (only visible if component is unpublished)

Component Properties

Every component has these core properties:

Basic Information

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

Technical Name: - Machine-readable identifier - Used in code generation - Example: customer_email

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

Data Type Configuration

XdString (Text):

Min Length: 1
Max Length: 255
Pattern: ^[A-Za-z\s]+$  (letters and spaces only)
Default Value: (optional)

XdCount (Integer):

Min Value: 0
Max Value: 999999
Units: count
Precision: 0 (no decimals)
Default Value: 0

XdQuantity (Decimal):

Min Value: 0.0
Max Value: 999999.99
Units: kg, meters, etc.
Precision: 2 (two decimal places)
Default Value: 0.0

XdTemporal (Date/Time):

Allowed Types: date, time, datetime, duration
Format: ISO 8601 (YYYY-MM-DD)
Min Date: 1900-01-01
Max Date: 2100-12-31
Default Value: (optional)

XdBoolean (True/False):

Default Value: true or false
Display As: checkbox, radio, toggle

Validation Rules

Required vs Optional: - Required: Must have a value - Optional: Can be null/empty

Pattern Validation (for XdString): - Regular expression patterns - Common patterns: - Email: ^[^@]+@[^@]+\.[^@]+$ - Phone: ^\+?[1-9]\d{1,14}$ - Zip: ^\d{5}(-\d{4})?$ - URL: ^https?://.*

Enumeration (allowed values):

Allowed Values: ['active', 'inactive', 'pending']
Default: 'active'

Range Constraints: - Minimum and maximum values - For numeric and temporal types

Example: Editing an Email Component

Before (AI-generated):

Label: email
Type: XdString
Max Length: 255
Pattern: (none)
Required: false

After (customized):

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

Saving Changes

1. Review Your Edits: Double-check all fields carefully
2. Choose Save Option:
3. "Save": Saves as draft - can still be edited later
4. "Save & Publish": Saves AND publishes - CANNOT be edited after this
5. Verify: You'll be redirected to the component detail page
6. 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

1. Navigate to Components: Go to /app/components
2. Click "Create New Component" button
3. Select Component Type from the modal:
4. Choose the appropriate SDC4 type
5. XdString for text, XdCount for integers, etc.
6. Fill in the Form:
7. Basic information (label, description, project)
8. Type-specific properties (length, range, format, etc.)
9. Validation rules
10. Default values
11. Save: Click "Save & Publish" or "Save"

Component Naming Best Practices

Technical Names: - Use lowercase with underscores: customer_email - Be descriptive: order_total_amount not total - Avoid abbreviations: quantity not qty - Be consistent: first_name, last_name (not firstName, surname)

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)
├── Personal Info Cluster
│   ├── first_name (XdString)
│   ├── last_name (XdString)
│   └── date_of_birth (XdTemporal)
├── Contact Info Cluster
│   ├── email (XdString)
│   ├── phone (XdString)
│   └── address (XdString)
└── Account Info Cluster
    ├── signup_date (XdTemporal)
    ├── status (XdString)
    └── total_purchases (XdCount)

Create a New Cluster

1. Navigate to Components: Go to /app/components
2. Click "Create New Component", then select "Cluster" from the type dropdown
3. Fill in the Form:
4. Label: "Contact Information"
5. Description: "Customer contact details"
6. Select project
7. Save: Click "Save & Publish" or "Save"

Add Components to Cluster

1. Edit the Component: Navigate to the component's detail page and click "Edit"
2. Select Parent Cluster: Use the dropdown to choose the cluster
3. Save: Click "Save & Publish" to apply changes

Validation and Quality Checks

Built-in Validation

SDCStudio validates your model automatically:

Type Validation: - Ensures components use valid SDC4 types - Checks for proper type configurations

Name Validation: - Unique technical names - Valid identifiers (no special characters) - No reserved keywords

Constraint Validation: - Min < Max for ranges - Valid regex patterns - Consistent enumeration values

Hierarchy Validation: - No circular references - Valid cluster nesting - Proper parent-child relationships

View Validation Issues

1. Navigate to Models: Go to /app/models
2. Find Your Model in the list
3. Click the Model to view its detail page
4. Check Validation Status:
5. ✅ Valid: Ready to publish
6. ⚠️ Warnings: Issues to review
7. ❌ Errors: Must fix before publishing

Fix Common Issues

"Duplicate technical name": - Rename one of the components - Ensure all names are unique within the model

"Invalid pattern": - Check regex syntax - Test pattern with regex tester - Use simpler pattern if complex

"Min greater than Max": - 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

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

1. Publish All Child Components First:
2. Navigate to each component used in your model
3. Review and verify each component is correct
4. Click "Save & Publish" for each component

5. Ensure ALL child components show "Published" status before proceeding

6. Publish the Data Model:

7. Navigate to Models: Go to /app/models
8. Find Your Model in the list
9. Click the Model to view details
10. Final Review: Verify ALL components are published and settings are correct

11. Click the "Publish" button on the model detail page

    • This can only be done ONCE
    • The button will disappear after publishing

12. Generate Package: After publishing the model, click "Generate Package (One-Time Only)"

13. This generates ALL export files (XSD, XML, JSON, HTML, etc.)
14. 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: - ✅ Download XSD schemas - ✅ Download XML instances - ✅ Download JSON schemas and instances - ✅ Download HTML documentation - ✅ Download complete ZIP package - ✅ 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

If You Need to Make Changes

If you discover issues after publishing:

1. Create a NEW model with a new version number or name
2. Copy component definitions from the published model as a reference
3. Make your changes in the new model
4. Test thoroughly before publishing the new version
5. Publish the new model when ready

Version Control Strategy: - Use version numbers in model names (e.g., "CustomerModel_v1", "CustomerModel_v2") - Document what changed between versions - Keep old versions as historical record

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 clusters - Create hierarchy that matches data structure - Use meaningful cluster names

Example: E-commerce Order

Order Model
├── Order Details Cluster
│   ├── order_id
│   ├── order_date
│   └── order_status
├── Customer Info Cluster
│   ├── customer_id
│   └── customer_email
├── Shipping Cluster
│   ├── shipping_address
│   ├── shipping_method
│   └── tracking_number
└── Payment Cluster
    ├── 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:

1. Edit Component
2. Add Semantic Link:
3. Search for ontology term
4. Select matching concept
5. Add predicate-object pair
6. Save: Component now has semantic meaning

See Semantic Enhancement Guide for details.

Reference Components

Reuse existing components:

1. Create Reference Component
2. Select Target Component
3. Configure Reference Type:
4. Direct reference
5. Copy with modifications
6. Save: Reference is created

Component Templates

Save frequently used components as templates:

1. Edit Component
2. Click "Save as Template"
3. Name Template: e.g., "Email Field Template"
4. Use Template: Select when creating new components

Troubleshooting

Can't Save Component

Validation Errors: - Check all required fields filled - Verify regex pattern syntax - Ensure min < max for ranges - Check for duplicate names

Permission Issues: - Verify you have edit permissions - Check model isn't locked - Ensure model isn't published (unpublish first)

Component Not Appearing

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

Hierarchy Issues: - Check parent cluster is correct - Verify component saved successfully - Look in "All Components" view

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 - Rename duplicate components - Complete required fields

Next Steps

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

Getting Help

• Troubleshooting Guide - Common issues
• Model Components Reference - Complete component reference
• Support: support@axius-sdc.com

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