Omnist documentation

Start here, in roughly this order:

Doc	What it covers
Quickstart	The shortest possible tour — one OML snippet, one schema, validate(), infer(). Read this if you just want to see it work.
Why Omnist	The differentiation case: a falsifiable thesis, a verified capability matrix against JSON/YAML/TOML/XML, a worked compatible_with comparison against jsonschema, and the honest non-goals.
User guide	The practical tour — documents, OML, the schema DSL and Python builder, validation, the schema operations, codecs, inference. Read this first.
OML	Omnist's own format: the only one with zero adjustments, and how it maps onto the Python Document.
The Schema model & DSL	Omnist's other central feature: record definitions, cardinality, the Python builder, and the comparison/inference operations.
A real-life example	One order schema validated against an order written in OML, plus a backward-compatibility check.
API reference	Every public name: Doc, Schema, the builders, codecs, validation results, and exceptions, with signatures.
Schema-directed deserialization	What changes (and what doesn't) about a Document's Python types when a schema is, vs. isn't, passed to a reader — the conversion rules, and why they're unambiguous.
Formats	How each format maps to the model and its caveats — OML · JSON · YAML · TOML · XML.
Model spec	The formal definitions of the Document and Schema models — self-contained, no paper required.
OML-Core grammar	The formal ABNF grammar for OML, verified against the parser: tokens, disambiguation rules, escaping, and documented limits.
Schema DSL grammar	The formal ABNF grammar for the schema DSL, verified against the parser: keywords, field syntax, cardinality, and the seven scalars.
Glossary	One definition per term used across the docs and code, grouped by concept area.
Testing	The test suite: layout, coverage tooling and target, the fuzzing approach, and what CI runs.
Repo layout	How the repo itself is organized: omnist/canonical/*.py module responsibilities, the docs page map, and the test file map.

The model in one minute

• A Document is a tree: a node is either a scalar value or an ordered list of labeled edges. An array is just a label that repeats — so the same Document represents JSON, YAML, TOML, XML, and OML (Omnist's own format).
• A Schema is named record definitions (closed named fields, each with a cardinality [min,max]), where each field's type is always exactly one fixed scalar (optionally nullable) or one Ref to a named record — referenced by name for reuse and recursion.
• Validate a Document against a schema, compare two schemas for backward-compatibility (compatible_with), or infer a schema from examples.
• Readers accept an optional schema= to upgrade leaves (ISO strings to real date/time/datetime, numeric types) to match the schema, when the conversion is value-exact.

from omnist import parse_schema, doc

s = parse_schema('''
    record Member { "name": string, "role": string }
    record Team   { "name": string, "members" [1,]: Member }
    root Team
''')
s.validate(doc({"name": "X", "members": [{"name": "Ann", "role": "dev"}]})).ok   # True