Model Schema
The canonical JSON Schema defining the structure of a Modellus model file. Use this schema for validation, code generation, and as the authoritative reference when building or interpreting models.
Top-Level Structure
A model file is a JSON object with two required fields and several optional ones:
| Field | Type | Description |
|---|---|---|
properties | ModelProperties | Simulation settings: independent variable, initial values, cases, angle unit, metadata |
board | Board | Array of shapes placed on the canvas |
preloadedData | PreloadedData | External CSV data loaded into calculator terms |
outlierIterations | OutlierIterations | Iterations flagged as outliers during analysis |
regressionTerms | RegressionTerms | Regression results computed from table selections |
ModelProperties
| Property | Type | Description |
|---|---|---|
name | string | Model title |
description | string | Brief description of the model's purpose |
instructions | string | Markdown instructions shown to users |
independent | object | { name, start, end, step } — the simulation variable and its range |
angleUnit | "radians" | "degrees" | Unit for all trigonometric functions |
casesCount | integer | Number of independent simulation cases |
initialValuesByCase | object | Map of case number → { termName: initialValue } for differential terms |
Board & Shapes
The board field is an array of shape objects. Each shape has:
| Field | Description |
|---|---|
type | Shape class name (e.g., "ExpressionShape", "ChartShape") |
id | UUID uniquely identifying the shape |
properties | Shape-specific configuration (position, terms, display settings) |
parent | Parent shape ID (for children of ReferentialShape) |
Agent Guidance Sections
The schema includes documentation-only sections under agentGuidance that provide step-by-step instructions for AI agents:
| Section | Purpose |
|---|---|
readingAModel | 8-step walkthrough for interpreting an existing model file |
identifyingTheScience | Pattern-matching guide to infer scientific principles from ODE structure |
buildingAModel | 7-step procedure for constructing a new model from a science intent |
stepSizeGuidance | How to choose the integration step for numerical stability |
Shape Roles
The shapeRoles section documents the semantic purpose and configuration of each shape type — what properties to set and how they interact with the calculator system.
Model Templates
The modelTemplates section provides complete specifications for common STEM problems (free fall, projectile motion, SHM, Lotka-Volterra, SIR model, etc.) that agents can use as construction blueprints.