Models

A ModelDefinition is a configuration object that describes the structure and schema of your data.

• Properties - The fields in your data structure
• Data types - Types for each property (string, int, boolean, etc.)
• References - Relationships to other models
• Data - Optional inline data

Think of models as blueprints or table schemas for your data.

dcupl supports these data types:

Type	Description	Example
string	Text values	"Laptop"
int	Whole numbers	42
float	Decimal numbers	99.99
boolean	True/false	true
date	Date/time values	"2025-01-15"
json	Complex nested objects	{ color: 'red' }
array	Arrays of values	['a', 'b']
Array<string>	Typed arrays	['red', 'blue']

Properties support additional options for indexing, computed values, and validation.

index

Manually control indexing for better query performance. Only index properties you'll actually query.

derive

Create computed properties from references. Pull values from referenced models automatically.

expression

Template-based computed properties using {{property}} syntax.

quality

Data validation rules including required fields and custom validators.

References link one model to another, enabling:

• Navigate between related data
• Query across relationships (deep queries)
• Build complex data structures
• Maintain data normalization

Single-Valued (Many-to-One)

Each item references one other item. Use for: Order → Customer, Product → Category.

Multi-Valued (One-to-Many)

Each item references multiple other items. Use for: Order → Products, User → Roles.

Create the inverse of another reference automatically using resolve.

Instead of manually maintaining both directions of a relationship, dcupl can compute the inverse for you.

Example: If Order → Customer exists, you can automatically get Customer → Orders.

The resolved reference is computed at initialization time and stays in sync with your data.

Models support additional configuration options:

Option	Description
keyProperty	Use a custom property as item identifier (default: 'key')
autoGenerateKey	Generate unique keys for items without one
autoGenerateProperties	Infer properties from data structure
supportsAutoCreation	Auto-create items when referenced
valueMappings	Transform values during data loading
meta	Attach metadata to the model
quality	Configure validation rules

Define quality criteria to validate your data at both model and attribute level.

Model-Level Quality

Set default quality rules that apply to all properties of a model.

Attribute-Level Quality

Override or extend quality rules for specific properties:

• required - Property must have a value
• validators - Custom validation rules (email, url, regex, etc.)

Quality issues are reported during data loading and can be accessed via the dcupl API.

Attach custom metadata to models and attributes for documentation, tooling, or frontend logic.

Model Meta

Describe the model itself:

• Display names and descriptions
• Data source information
• Icons or UI hints

Attribute Meta

Describe individual properties:

• Labels for forms or tables
• Tooltips and help text
• Formatting hints (currency, percentage)
• Source system field mappings

Meta is a free-form object - structure it however fits your needs.

• Use clear, descriptive keys - Product, CustomerOrder instead of Item, Data
• Keep models focused - Each model should represent a single entity
• Use specific types - int for prices, boolean for flags, not string
• Use typed arrays - Array<string> instead of array
• Don't over-index - Only index properties you'll query, indexing has memory cost
• Choose the right reference type - Single-valued for many-to-one, multi-valued for one-to-many
• Limit reference depth - Deep queries (3+ levels) add overhead