Metadata-Version: 2.5
Name: valgebra-jsonschema
Version: 0.0.4
Summary: JSON Schema read into valgebra's sets: membership as the specification states it, and inclusion decided between two schemas.
Project-URL: Repository, https://github.com/ppigazzini/valgebra-jsonschema
Project-URL: Documentation, https://ppigazzini.github.io/valgebra-jsonschema/
Project-URL: Changelog, https://github.com/ppigazzini/valgebra-jsonschema/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/ppigazzini/valgebra-jsonschema/issues
Author: Pasquale Pigazzini
License-Expression: MIT OR Apache-2.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Keywords: json-schema,mcp,subschema,valgebra,validation
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: annotated-types>=0.8.0
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: valgebra>=0.0.31
Description-Content-Type: text/markdown

# valgebra-jsonschema

JSON Schema read into [valgebra](https://github.com/ppigazzini/valgebra)'s sets, so a schema
answers two questions: whether a value belongs, as the specification states it, and whether
everything one schema admits another admits too.

📖 **Documentation: <https://ppigazzini.github.io/valgebra-jsonschema/>**

🤖 **For AI assistants and coding agents:** the documentation is also published as
[`llms.txt`](https://ppigazzini.github.io/valgebra-jsonschema/llms.txt) (a curated manifest)
and [`llms-full.txt`](https://ppigazzini.github.io/valgebra-jsonschema/llms-full.txt) (the
full text, including the API reference) per the [llmstxt.org](https://llmstxt.org)
convention.

```python
from valgebra_jsonschema import compile_schema

# What an MCP server lists for a tool: its arguments, as JSON Schema.
tool = {
    "name": "get_weather",
    "inputSchema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "minLength": 1},
            "days": {"type": "number", "minimum": 1, "maximum": 7},
            "units": {"enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
    },
}
arguments = compile_schema(tool["inputSchema"])

assert arguments.is_valid({"location": "Paris", "days": 3})
assert not arguments.is_valid({"days": 3})
assert not arguments.is_valid({"location": "Paris", "days": 8})

# `1` and `1.0` are one JSON number, and `true` is none.
assert compile_schema({"type": "integer"}).is_valid(1.0)
assert not compile_schema({"type": "integer"}).is_valid(True)

# The next release of the tool takes another unit. Every call that was valid still is,
# and the converse fails: that is a compatible change, decided without running either.
wider = compile_schema(
    {
        "type": "object",
        "properties": {
            "location": {"type": "string", "minLength": 1},
            "days": {"type": "number", "minimum": 1, "maximum": 7},
            "units": {"enum": ["celsius", "fahrenheit", "kelvin"]},
        },
        "required": ["location"],
    }
)
assert arguments.relation_to(wider) == "subset"
assert wider.relation_to(arguments) == "not_subset"
```

`relation_to` answers `subset`, `not_subset` or `undecided`. It is `undecided` where valgebra
can prove neither, which is never a wrong proof, and a keyword this package does not read raises
`Unsupported` naming it, since skipping one would admit values the schema refuses. A schema
that spells its values out, with `const`, `enum`, or an `anyOf` or `oneOf` of them, is related
by each value: `constants(schema)` lists them, and the schema lies inside another exactly
where `is_valid` admits each, a keyword valgebra reads as a predicate included.

[The recipes](https://ppigazzini.github.io/valgebra-jsonschema/recipes/) do five tasks end to end: a model's tool call checked against the schema it was shown, a
schema change checked before release, a schema split across documents, files checked against a
schema, and what a schema asserts, keyword by keyword.

## What it reads

Drafts 2020-12, 2019-09, 07, 06 and 04, all but the first through `upgrade`, and a document
naming any other dialect fails saying so, as the Model Context Protocol asks
([reading an MCP tool](https://ppigazzini.github.io/valgebra-jsonschema/mcp/)).
Patterns follow ECMA-262, as the specification requires, and numbers compare by value: `1` and
`1.0` are one number, and `true` is none. `format` is an annotation, as 2020-12 makes it, and
`assert_format=True` reads nine of them as assertions. A `$ref` resolves against the base URI it
sits under, within the document or to one passed in `documents={uri: document}`; nothing is
fetched.
[How it works](https://ppigazzini.github.io/valgebra-jsonschema/how-it-works/) follows a schema from its document to both answers, a diagram for each step;
[the compiler page](https://ppigazzini.github.io/valgebra-jsonschema/compiler/) says how each keyword becomes a set, and
[the conformance page](https://ppigazzini.github.io/valgebra-jsonschema/conformance/) holds the inventory and the ledger of
differences.

## Measured

```bash
uv run python tools/suite.py --check docs/studies/json-schema-test-suite.json
uv run python tools/corpus.py --check docs/studies/jsonschemabench.json
uv run python tools/containment.py --check docs/studies/containment.json
```

- **Against the official JSON-Schema-Test-Suite**: draft 2020-12 with the four optional files on
  regular expressions and large numbers, 1393 of the 1393 cases it runs; draft 2019-09, 1256 of
  1256; draft-07, 929 of 929; draft-06, 841 of 841; draft-04, 618 of 618. Skipped: the five
  cases naming a custom meta-schema as their dialect.
- **Real-world schemas** (JSONSchemaBench, 9558 schemas from GitHub, the JSON Schema Store,
  Kubernetes and function-calling data): 9486 compile, none crashes; membership differs from the
  `jsonschema` package's on 13 of 418210 values, each a reading the ledger records.
- **Inclusions** (the JSON Schema containment test suite, 10890 labeled questions): 7049 proven,
  6 against a label, each a wrong label; each of the 378 refutations against a label is a wrong label, which
  [the results page](https://ppigazzini.github.io/valgebra-jsonschema/results/) names.

## Install

On Python 3.11 or later, from PyPI, with valgebra, a Rust extension published as wheels:

```bash
pip install valgebra-jsonschema
```

## License

MIT or Apache-2.0, at your option.
