DataCanon input

A DataCanon Instance (DCI) is a value in DataCanon’s data model. SchemaProjector accepts a Mapping DCI whose keys are String DCIs. The values already have DataCanon Types (DCTs); the schema can optionally constrain them. Parsing text and converting conventional objects happen before projection.

From conventional objects

from data_canon import as_dc_instance
from data_schemer.schema_projector import SchemaProjector

projector = SchemaProjector({"variables": {"matrix": {}, "iterations": {"type": "Integer"}}})
input_dci = as_dc_instance({"matrix": [[2, -1], [-1, 2]], "iterations": 20})
projection = projector.get_projection(input_dci)

as_dc_instance() applies DataCanon’s conversion rules. The resulting DCI is the input to DataSchemer (DS). Passing the conventional dictionary directly to get_projection() is an error.

The String-key restriction applies to the Mapping that supplies schema fields and to Mappings supplying child-schema data. A Mapping used as a field value can retain arbitrary DCI keys:

input_dci = as_dc_instance({"samples": {("sensor", 0): [1.0, 2.0]}})
projection = SchemaProjector({"variables": {"samples": {}}}).get_projection(input_dci)
assert projection.data["samples"][("sensor", 0)] == [1.0, 2.0]

From Shorthand

from data_canon import parse_shorthand

input_dci = parse_shorthand('{"matrix": [[2, -1], [-1, 2]], "iterations": 20}')
projection = projector.get_projection(input_dci)

Shorthand preserves structured numerical DCIs. For example, sqrt(3) describes a Power DCI, and 1/2 * sqrt(3) describes a Product containing a Fraction and a Power. DataCanon (DC) does not perform mathematical simplification during parsing.

Optional input preprocessing

Preprocessing makes manually written input easier to maintain. Enable it explicitly when calling the DC parser:

source = """
diagonal = 2
off_diagonal = -1 |
{
  "matrix": <diagonal off_diagonal; off_diagonal diagonal>,
  "iterations": 20
}
"""
input_dci = parse_shorthand(source, preprocess=True)
projection = projector.get_projection(input_dci)
assert projection.data["matrix"] == [[2, -1], [-1, 2]]

Substitutions insert DC structure. Compact List notation establishes nested Lists. An explicit eval(...) requests scalar mathematical evaluation during preprocessing:

input_dci = parse_shorthand(
    'side=2.5 | {"area": eval(side * side)}',
    preprocess=True,
)
projection = SchemaProjector({"variables": {"area": {}}}).get_projection(input_dci)
assert projection.data["area"] == 6.25

Preprocessing belongs to DC’s input facilities. SchemaProjector receives the resulting DCI and does not evaluate text inside String DCIs.

Application-defined command-line presets are available through SCL’s per-field substitutions property. See Application-defined substitutions for an identity-matrix example using 2 * I. Presets affect command-line option values; SchemaProjector continues to receive DCIs without interpreting strings.

From files

For a standalone projector, load the DCI before projection:

from data_canon import read

input_dci = read("calculation.dcb")
projection = projector.get_projection(input_dci)

DC’s read() handles canonical binary .dcb, strict Shorthand .dcs, and DC HDF5 files. For a standalone preprocessed Shorthand file, read its text and call parse_shorthand(..., preprocess=True) explicitly. If external resources are present, use an appropriate source when converting conventional output; DC’s persistence readers retain source context automatically.

SchemaCommandLine (SCL) provides an additional input boundary. It accepts .dcs with preprocessing, .dcb, DC .h5/.hdf5, and DC YAML .yaml/.yml. Its source loading retains context for deferred external-resource access. See SCL input files.

YAML interchange

Use DC’s YAML interchange when importing YAML directly:

from data_canon import parse_yaml

input_dci = parse_yaml("""
iterations: 20
samples:
  $ ("sensor", 0): [1.0, 2.0]
phase: $ complex(1/2, 1/2 * sqrt(3))
""")
projection = SchemaProjector({"variables": {
    "iterations": {"type": "Integer"}, "samples": {}, "phase": {},
}}).get_projection(input_dci)

The $ marker embeds strict DC Shorthand in YAML scalars, including Mapping keys. YAML sequences become Lists. YAML airlocks do not run Shorthand preprocessing.

For DC syntax, representations, and custom conversion registries, consult the DataCanon documentation.