Understanding schemas

DataSchemer (DS) applies a schema definition to input represented as DataCanon Instances (DCIs). A schema describes which fields an application accepts and how those fields should be checked and prepared. It is not the input data itself.

Definitions, variables, and input

A schema definition is an ordinary Python dictionary. Its variables mapping describes named input fields, with optional DataCanon Type (DCT) constraints, defaults, and other rules:

from data_canon import as_dc_instance
from data_schemer.schema_projector import SchemaProjector

definitions = {
    "calculation": {
        "variables": {
            "iterations": {"type": "Integer", "optional": True, "default": 20},
            "label": {"type": "String", "optional": True},
        },
    },
}

projector = SchemaProjector(definitions, schema_name="calculation")
projection = projector.get_projection(as_dc_instance({"label": "example"}))
assert projection.data == {"iterations": 20, "label": "example"}

The input is a Mapping DCI. The projection is a separate result that validates supplied fields and applies schema defaults. The original input remains available independently of the processed result. Applications can request conventional Python objects from the projection when needed.

A type property constrains the DCT of a supplied value; it does not request implicit conversion between different DCTs. See Schema projection.

Inheritance versus children

These relationships serve different purposes:

  • Inheritance reuses and modifies schema definitions. A derived schema may inherit variables and override their properties. It does not nest data.
  • Child schemas describe nested input. A parent schema names child schemas, and a supplied child Mapping is projected using that child’s definition. Children do not need to inherit from their parents.

For example:

definitions = {
    "base": {"variables": {"iterations": {"type": "Integer"}}},
    "run": {"inherit": ["base"], "child_schemas": ["output"]},
    "output": {"variables": {"filename": {"type": "String"}}},
}

projection = SchemaProjector(definitions, schema_name="run").get_projection(
    as_dc_instance({"iterations": 10, "output": {"filename": "result.dat"}})
)
assert projection.data == {"iterations": 10}
assert projection.child_projections["output"].data == {"filename": "result.dat"}

The run schema inherits the iterations definition, while output is a separately projected child. An absent child remains absent; merely declaring it does not supply its input. See Schema composition and Child schemas.

Mapping schemas and pipeline schemas

An ordinary schema projects a Mapping DCI of named fields. A schema declared with pipeline: true instead projects an ordered List of single-operation Mappings. Pipeline operations may repeat, and their order is preserved. Child schemas can also participate in pipeline structures.

See Pipeline schemas for examples and rules.

From a schema to a command line

SchemaProjector handles projection without a CLI. SchemaCommandLine (SCL) adds argument parsing, file input, nested command navigation, and optional application construction. Both use the same schema definitions and projection rules. See SchemaCommandLine.