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.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.