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, OSD and the 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 & OSD	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.
Real-world examples: overview	Four real, external formats — pyproject.toml, package.json, a GitHub Actions workflow, sitemap.xml — each run end to end, with a comparison table and the four gap categories OSD's schema algebra can't express.
API reference	Every public name: Doc, Schema, the builders, codecs, validation results, and exceptions, with signatures.
CLI	The omnist command-line tool, fully implemented: format, convert, check, validate, infer, and seven schema subcommands (format/normalize/prune/is-empty/extract/compatible-with/equivalent), specified in the CLI spec.
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.
OSD grammar	The formal ABNF grammar for OSD, 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/*.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 Markup Language, 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. Written as OSD (Omnist Schema Definition), Omnist's own schema text syntax.
• 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 Database { "type": string, "server": string, "port": integer }
    record Service  { "host": string, "port": integer,
                       "databases" [1,]: Database, "tags" [0,]: string }
    root Service
''')
s.validate(doc({"host": "api.internal", "port": 8443,
                "databases": [{"type": "prod", "server": "db1.internal.example.com", "port": 5432}],
                "tags": ["prod", "us-east"]})).ok   # True