Schema documentation

The canonical materials schema is the single persistence contract for the materials subsystem. This guide covers structure, value encoding, and how to convert external files for import into WeemsCanvas.

Contract material-canonical.schema.jsonInputs JSON, XML, CSVEndpoint POST /api/materials/import

Compatibility: Target schema_version=1.1.1 for imports. Re-run parity review whenever adapter or ontology versions change.

Start here

Pick the goal that matches your workflow.

Import external file

Upload or post JSON, XML, or CSV and convert it into canonical schema documents.

Pick source format
Map identity + units
Generate manifest

Open Materials

Validate canonical quality

Review warnings, unsupported fields, fidelity score, and loss events before publishing.

Check mapping_report warnings
Verify parity tier
Resolve silent drops

Review Quality Gates

Inspect mapping diagnostics

Use material detail diagnostics to trace source-to-canonical decisions and loss severity.

Inspect mapping decisions
Inspect loss event paths
Verify referential integrity

Open Troubleshooting

Overview

Why a canonical contract exists and what it enforces.

External material representations may vary, but stored records must converge to the same deterministic structure to support reproducible compute, versioning, parity analysis, and cross-tool interoperability.

Single source of truth

Backend and frontend converge on canonical field names and value unions, preventing drift between UI projection and persisted documents.

Loss visibility

Every conversion retains mapping decisions and fidelity metrics so dropped, transformed, or unresolved semantics are never hidden.

Compute compatibility

Canonical compute fields expose normalized property data for engine-facing workflows while preserving provenance back to source input.

Canonical flow map

End-to-end path from source file to trusted material record.

Capture source input

Collect raw material payload from JSON, XML, or CSV source systems.

Expected output: raw_text + source_format

Failure signal: Unknown record root or malformed document shape.

Detect parser and adapter path

Choose canonical pass-through or adapter mapping strategy.

Expected output: mapping_report.adapter + parser path

Failure signal: Incorrect adapter path causes widespread unmapped fragments.

Map canonical identity and properties

Normalize material identity, value kinds, and unit envelopes.

Expected output: material + canonical_structure + canonical_compute

Failure signal: Unit ambiguity and unstable IDs lower parity.

Emit conversion trace

Record every mapping decision, warning, and loss event.

Expected output: conversion_manifest

Failure signal: Silent transformations hidden from users.

Run quality checks

Validate schema shape, parity score, reference integrity, and unresolved units.

Expected output: fidelity_report + quality verdict

Failure signal: Publishing low-fidelity materials into shared libraries.

Publish and inspect material detail

Store versioned material and review diagnostics before downstream use.

Expected output: material_uid + versioned canonical record

Failure signal: Consumers use records without reviewing diagnostics.

Schema anatomy

Top-level canonical document fields.

A canonical document consists of versioning headers, a material identity block, structured data, compute projections, and a conversion manifest. All top-level fields are required except extensions.

Field	Required	Purpose
`schema_version`	required	Canonical schema contract version. Current value: 1.1.1.
`ontology_version`	required	Material ontology snapshot used for concept keys and semantic interpretation.
`adapter_set_version`	required	Adapter package version used during conversion and mapping decisions.
`material`	required	Identity payload: material id, class, display name, and base metadata.
`canonical_structure`	required	Graph-like structured data: parameters, datasets, resources, dependencies, conditions.
`canonical_compute`	required	Compute-ready property projections used by solver-facing paths.
`conversion_manifest`	required	Conversion decisions, warnings, loss events, and fidelity metrics.
`extensions`	optional	Forward-compatible extension bag. Keys should use x_* style naming.

canonical_structure

Declarative data graph: groups, parameters, datasets, dependencies, and resources.

Use this section for physics-facing source-of-truth data. Parameters carry values and units, datasets store multi-condition property points, and resources link large external tabular payloads.

Keep IDs stable and reference-safe to maintain referential integrity across conditions, methods, and phase or system contexts.

canonical_compute + conversion_manifest

Compute projections and conversion traceability emitted by ingestion.

Compute properties expose normalized values for downstream solver integration. The conversion manifest records mapping decisions, loss events, and parity score.

Treat the conversion manifest as mandatory QA output. A successful import with low fidelity still needs correction before production use.

Schema explorer

Expand each node to see why it matters in real imports.

Defines stable identity and classification used across all libraries.

material_iddisplay_namematerial_classaliasesextensions

Value kinds

How property values are encoded.

Property values use a discriminated union keyed by kind. Choose the smallest expressive kind that preserves source semantics without ambiguity.

numeric

Single scalar values such as density at reference conditions.

{ "kind": "numeric", "value": 7850 }

table

Properties varying across one or more axes, such as temperature-dependent conductivity.

{ "kind": "table", "input_axes": [...], "output_unit": "W/(m*K)", "data": [[293, 15.5], [350, 17.2]] }

tensor

Directional or anisotropic properties represented as ordered components.

{ "kind": "tensor", "shape": "3x3", "components": [...], "component_order": ["xx", "yy", "zz", "xy", "yz", "xz"] }

function

Closed-form constitutive expressions tied to a known engine.

{ "kind": "function", "engine": "symbolic", "expression": "k0 + a*T", "variables": ["T"] }

expression

Template or math expressions that must preserve source expression semantics.

{ "kind": "expression", "expression_language": "canonical_math", "text": "E/(2*(1+nu))" }

reference

Pointers to other canonical entities such as parameters, groups, or conditions.

{ "kind": "reference", "target_kind": "parameter", "target_id": "param_density", "resolution_status": "resolved" }

missing

Explicitly model absent values instead of silently dropping source data.

{ "kind": "missing", "missing_reason": "unknown" }

Value-kind decision assistant

Source pattern	Use	Avoid
Single scalar with one unit	`numeric`	Encoding one number as table with synthetic axis.
Property varying by temperature/pressure/composition	`table`	Dropping axis metadata or row ordering.
Directional matrix or anisotropy components	`tensor`	Flattening tensor components into string blobs.
Equation intended for runtime evaluation	`function / expression`	Converting formulas to sampled tables without traceability.
Unavailable/unknown value	`missing`	Silently dropping fields or writing null without reason.

Conversion playbook

Five steps to convert external files for import.

Follow this process when converting external material files into canonical schema for WeemsCanvas import.

1
Detect source format
Determine whether the file is a canonical JSON pass-through or requires adapter mapping for XML, CSV, or external JSON.
2
Normalize identity
Map source ID, name, version, and category into deterministic material identity fields.
3
Map properties
Convert source properties into canonical value kinds and attach explicit unit envelopes.
4
Emit manifest
Record all mapping decisions, loss events, and warnings in conversion_manifest.
5
Validate and import
Validate against the schema, inspect mapping_report, then import into the target library.

Import request payloadhttp

POST /api/materials/import
Content-Type: application/json

{
  "source_format": "json",
  "raw_text": "{...source file text...}",
  "library_uid": "lib_abc123"
}

Import preflight checklist

Validate these gates before running production imports.

Identity determinism

Pass signal: Stable source keys map to stable material_id and version.

Failure signal: material_id changes across identical source payloads.

Action: Apply deterministic ID strategy using source id + namespace.

Unit normalization

Pass signal: Each numeric/table field includes canonical_unit and conversion_status.

Failure signal: Unresolved unit tokens or unitless dimensional values.

Action: Extend unit map and retain original_unit_token in envelope.

Value-kind correctness

Pass signal: All properties use the smallest correct kind without lossy coercion.

Failure signal: Tables as numeric, formulas as strings, missing values dropped.

Action: Re-map value kinds and explicitly emit kind=missing when needed.

Table integrity

Pass signal: Axis order, monotonicity, and row shape are valid.

Failure signal: Malformed rows or inconsistent axis metadata.

Action: Ensure each row includes all axis values + output value.

Traceability

Pass signal: mapping_decisions and fidelity_report are complete.

Failure signal: Import succeeds but no diagnostics for dropped fields.

Action: Emit mapping decisions and loss events for all transforms/drops.

Format guides

JSON, XML, and CSV specifics.

Input format decision matrix

Format	Best path	What to validate
Canonical JSON	Pass-through validation against canonical schema.	Required top-level fields, value kind shapes, conversion manifest present.
External JSON	Adapter mapping (record roots + field aliases) to canonical document.	Identity mapping, property kind inference, unit normalization, unsupported fields.
XML	XML parser + adapter map to canonical parameters, datasets, and resources.	XPath coverage, missing token handling, structured conversion warnings.
CSV	Tabular ingest with explicit schema for independent and dependent columns.	Column role assignment, units per axis, missing tokens, row shape consistency.

Adapter-aware JSON mapping

Keep source records under recognizable roots such as materials, items, records, or data for predictable detection.
Use stable property field names such as name, type, value, and unit to minimize ambiguous inference.
Include source references when available so provenance remains inspectable after conversion.

When to use extensions

If source fields are valuable but not yet canonically modeled, preserve them in extension fields instead of discarding.
Keep extension keys prefixed and machine-readable, such as x_source_vendor and x_source_hash.
Avoid storing fields in extensions when a canonical field already exists; always map canonical first.

Examples

Copy-ready conversion snippets.

Compare a pre-conversion source payload against the canonical output shape to understand what the adapter must produce.

External source JSONjson

{
  "materials": [
    {
      "id": "steel_304",
      "name": "Stainless Steel 304",
      "type": "metal",
      "version": "1.0.0",
      "properties": [
        { "name": "density", "type": "numeric", "value": 7930, "unit": "kg/m^3" },
        {
          "name": "thermal_conductivity",
          "type": "table",
          "inputs": ["temperature"],
          "input_units": ["K"],
          "output_unit": "W/(m*K)",
          "rows": [[293, 14.6], [373, 16.2], [473, 18.4]]
        }
      ]
    }
  ]
}

Canonical material documentjson

{
  "schema_version": "1.1.1",
  "ontology_version": "1.1.1",
  "adapter_set_version": "1.1.1",
  "material": {
    "material_id": "mat_steel_304",
    "display_name": "Stainless Steel 304",
    "material_class": "metal"
  },
  "canonical_structure": {
    "parameters": [
      {
        "parameter_id": "param_density",
        "concept_key": "mass_density",
        "role": "output",
        "value": { "kind": "numeric", "value": 7930 },
        "unit": { "canonical_unit": "kg/m^3", "conversion_status": "exact" }
      }
    ],
    "datasets": [
      {
        "dataset_id": "dataset_thermal_conductivity",
        "system_id": "sys_material_base",
        "properties": [
          { "property_id": "prop_k", "concept_key": "thermal_conductivity", "value_kind": "table" }
        ],
        "points": [
          {
            "point_id": "point_k_table",
            "property_values": [
              {
                "property_id": "prop_k",
                "value": {
                  "kind": "table",
                  "input_axes": [
                    { "axis_id": "axis_temperature", "concept_key": "temperature",
                      "unit": "K", "order": 0, "monotonicity": "increasing" }
                  ],
                  "output_unit": "W/(m*K)",
                  "interpolation": "linear",
                  "extrapolation": "error",
                  "data": [[293, 14.6], [373, 16.2], [473, 18.4]]
                }
              }
            ]
          }
        ]
      }
    ],
    "resources": []
  },
  "canonical_compute": { "compute_properties": [] },
  "conversion_manifest": {
    "conversion_id": "conv_2026_02_25_steel_304",
    "mapping_decisions": [],
    "fidelity_report": { "score": 1, "silent_drop_count": 0, "loss_events": [] }
  }
}

What should match after conversion

Identity parity: Source identity maps deterministically to material.material_id and display_name.
Unit parity: All numeric and table outputs carry canonical units and conversion status.
Semantic parity: No important source fields disappear without manifest warnings or extension preservation.

Post-import review

Inspect these signals immediately after each import.

Signal	Inspect	Expected outcome
Adapter + parsing path	`mapping_report.adapter`	Chosen adapter matches your source family and schema profile.
Warnings + unsupported fields	`mapping_report.warnings / unsupported_fields`	Warnings are reviewed; unsupported fields are either mapped or preserved in extensions.
Parity and silent drops	`fidelity_report.score / parity_tier / silent_drop_count`	Parity tier is acceptable and silent drops are zero or explained.
Loss event trace	`fidelity_report.loss_events[].canonical_path`	Every medium/high/critical loss has a clear mitigation decision.
Reference integrity	`canonical_structure.referential_integrity`	No unresolved references or cycles before publishing.

Quality gates

Required checks before publishing a material.

Treat these checks as required before considering a converted material production-ready.

Ensure material identity is deterministic: stable source IDs must map to stable material_id values.
Keep all units explicit; avoid unitless numeric values unless truly dimensionless.
Do not drop unknown fields silently; emit manifest warnings or extension data.
For table data, verify axis order, monotonicity, and interpolation/extrapolation policy.
Represent missing values as kind=missing instead of null-only payloads.
Require unresolved references to be visible in referential_integrity counters.
Review mapping_report for unsupported fields before publishing the material.

Key report signals

mapping_report.adapter: which parser or mapping path was selected.
mapping_report.warnings: non-fatal issues requiring review.
fidelity_report.score and loss_events: parity quality and where information changed or dropped.

Operational rule

Successful import is necessary but not sufficient. Only publish materials that pass schema validation and have acceptable fidelity with no unexplained loss events.
Keep conversion manifests versioned with source inputs to make future migrations reproducible and auditable.

Troubleshooting

Diagnose by signal, then apply the targeted fix.

Likely reason: The payload does not match canonical pass-through and no adapter mapping path can detect it confidently.

Recommended fix: Normalize record roots to known adapter paths such as materials, items, records, or data. Add a mapping profile under canonical json-adapter-maps before retrying.

Need help beyond this guide? Open the support page or review canonical schema assets in the repository for adapter maps and version metadata.

Open Support Open Materials

Schema versioning

Version policy for safe upgrades and repeatable imports.

Active contract

Schema docs and import guidance are currently aligned to 1.1.1.

Current canonical schema is 1.1.1 and should be treated as the default import target.
Reject stale adapter mappings that cannot produce required 1.1.1 fields.
Track mapping_spec_version and adapter_set_version for reproducible re-imports.
Re-run parity review whenever schema_version, ontology_version, or adapter_set_version changes.

Next: Support