Working with Models and Projects

Reading time: ~5 minutes | Level: Beginner Prerequisites: Walkthrough 2: SDCStudio Overview

What You'll Learn

• How projects organize your work in SDCStudio
• How to create a model using the Model Wizard
• The model lifecycle from Draft to Published
• Versioning strategies for evolving models
• Tips for organizing a multi-model project

Projects

What Projects Are

A project is a top-level container that groups related data models, components, data sources, and clusters. Use projects to organize by:

• Domain: "Healthcare Patient Records", "E-Commerce Orders"
• Department: "Finance Data Models", "HR Analytics"
• Initiative: "Q1 Integration Project", "Data Warehouse Migration"

Each project is public or private, shown as a badge in the list. Public projects, including the public libraries (Default, NIEM, FHIR, NIH_CDE and fourteen more), are curated; there is no user toggle. Their published components can be copied into your own project or referenced from it.

Creating a Project

Your account already has one project, created with it: named after you, private, and set as your default. You can build in it, rename it on its page, or create another to keep this work separate.

New accounts fund the wallet with at least $10 (10,000 credits) at /app/welcome before anything else in the app opens; the public catalog API needs no account.

1. On the dashboard, click New Project (or open Projects at /app/projects and click New Project)
2. Fill in:
3. Name: a descriptive name (for example "Customer Analytics")
4. Description (optional): purpose and scope of the project
5. Click Create Project

You are taken to the project page. It has no tabs: a details card (Name, Description, Creator, Created, Last Updated, with Edit and Delete for the owner) and a Data Models (n) list with a New Model button.

Project Organization Tips

One project per domain area: Keep healthcare models separate from finance models. The project's name and description are given to the AI as context during data processing, so a focused project gets better suggestions.

Name projects descriptively: "Customer Management v2" is more useful than "Project 3".

Use descriptions: Future you (and your colleagues) will thank you for explaining what each project is for.

Data Models

What a Model Is

A data model is the core SDC4 artifact. It contains: - A Data cluster (which contains components) - Metadata: title, description, about, Dublin Core fields, language, encoding - Sovereign identity: an auto-generated CUID2 instance_id (mandatory, read-only) - Source provenance (optional): source_instance_id and source_version_id for tracking data lineage from originating systems - Status: Draft, Published, or Retired

Models are typically created automatically when you upload a data file and the AI processes it. But you can also create models manually.

Creating a Model with the Model Wizard

1. Open Data Models (/app/models)
2. Click New Model; the Model Wizard opens at /app/models/wizard. The New Model button on a project page and the New Data Model card on the dashboard open the same wizard; the smaller Advanced Form link beside either button opens a single-page form with the same fields
3. The wizard has five steps:
4. Basics: Project (required), Model Title (required), Description, About
5. Metadata (optional): Dublin Core fields (Subject, Source, Rights, Relation, Coverage, Publisher), language, encoding
6. Authors (optional): Author, Contributors
7. Data & Provenance (optional): Data Cluster, Subject, Provider, Participations, Protocol, Workflow, Access Control Service, Audits, Attestation, Related Links, and the Source Provenance identifiers (Source Instance ID, Source Version ID)

8. Review & Save

9. Click Create Model (500 credits; a sovereign instance_id CUID2 is auto-generated)

After creation, the model is in Draft status. You then: - Add components (manually or from AI processing) - Organize them into a cluster and choose it as the model's Data Cluster - Review and refine - Publish when ready

The Model Lifecycle

Draft → (edit freely) → Published → (optional) Retired

Draft: The model can be edited. Components can be added, removed, or modified. This is where you do all your work.

Published: The model is locked. No further edits are possible. This enables output generation (the Model Generation card).

Retired: Taken out of the lists by the owner or an admin. It stays published and resolvable by its identifier, so nothing that uses it breaks.

There is no way to move backward in this lifecycle. Draft → Published is permanent; there is no Unpublish, and a published model cannot be deleted. The API refuses edits to a published model too (409 published_is_immutable).

The Data Models list offers the same actions on each row, each only when you are allowed to: Publish and Delete on a draft, Retire on a published model.

Viewing a Model

The model detail page shows:

• Model metadata: Title, Description, Project, Instance ID, Source Instance ID, Source Version ID, Status, Created, Last Updated
• Data cluster: the grouping of all data components
• Component list: all components in the model with their types and status
• Actions: while Draft, Publish (owner and admins), Edit and Delete; once Published, Copy and Retire
• Model Generation card (after publication): Generate, then Download Complete Package (ZIP); after that, the Generate App (choose one) card

Versioning Strategy

Since publication is irreversible, versioning is how you evolve models over time.

Naming Convention

Use a consistent naming pattern:

{ModelName} v{version}

Examples:
  Customer Demographics v1
  Customer Demographics v2
  Patient Vitals v1.0
  Patient Vitals v1.1

When to Create a New Version

Create a new version when: - You discover errors in a published model - Requirements change and fields need to be added or modified - Validation rules need updating - New semantic links need to be applied

Version Workflow

1. Copy the published model: the Copy button on its detail page creates an unpublished "COPY -- ..." model with prov:wasDerivedFrom lineage to the original (Copy is refused for retired sources)
2. Rename the copy with the new version; the "COPY -- " prefix blocks publishing until you do
3. Copy and correct the components that need to change, and update the cluster
4. Organize and test: verify all changes
5. Publish, following the standard bottom-up process
6. Retire the previous version and record what changed in the new model's description

SDC Versioning Convention

The SDC ecosystem uses a modified semantic versioning scheme:

MAJOR.MINOR.PATCH

• MAJOR = SDC Reference Model version (currently 4 for SDC4)
• MINOR = Feature releases for your artifact
• PATCH = Bug fixes and minor updates

All SDC4-compliant artifacts use 4.x.x versioning. The major version always matches the Reference Model version.

Multi-Model Projects

For projects with multiple related models:

Shared Components

Components can be shared across models within a project. Create common components (like "Email Address" or "Currency Amount") once, then include them in multiple models via clusters.

Model Dependencies

If one model references concepts from another (for example an "Order" model references a "Customer" model), document this relationship in the model descriptions. SDCStudio does not enforce cross-model dependencies directly, but clear documentation prevents confusion.

Organization Pattern

A typical multi-model project might look like:

Project: E-Commerce Platform
├── Model: Customer v1
│   └── Cluster: Customer Data
│       └── customer_id, name, email, phone, street, city, state, zip
├── Model: Product Catalog v1
│   └── Cluster: Product Data
│       └── product_id, name, description, price, currency, discount
└── Model: Order v1
    └── Cluster: Order Data
        └── order_id, order_date, status, product_ref, quantity, unit_price, method, amount, transaction_id

Summary

• Projects organize related models, components, and data sources
• Models are the core SDC4 artifacts, created automatically from uploads or manually via the Model Wizard
• The model lifecycle is Draft → Published (irreversible), with Retired as an optional final state
• Use Copy plus a version suffix (v1, v2, v3) to evolve models after publication
• Shared components enable reuse across models within a project

Where to Go from Here

You have now completed the full walkthrough series. Here are paths for continued learning:

• User Guides: comprehensive reference documentation for every feature
• SDC4 Type Reference: complete SDC4 type specifications
• Generating Outputs Guide: deep dive into each output format
• Semantic Enhancement Guide: advanced ontology integration
• Walkthrough index: the full list