# OpenPredicate

> One JSON Schema for the filter half of a search API — $ref it from an OpenAPI document, or inline it as an MCP tool's inputSchema. It specifies the predicate and deliberately nothing else — no projection, ordering, pagination or joins — which is what lets one grammar serve every search endpoint in an API. Grammar v0.4.0, release v0.6.0, MIT licensed.

The grammar is a single JSON Schema file with no dependencies, published at an immutable versioned
URL and pinned by `$id`. Reference it with `$ref` from an OpenAPI document, or inline it as an MCP
tool's `inputSchema`.

## Start here

- [How to design a search API](https://openpredicate.tech/guide/): the five decisions behind a search endpoint — where the filter goes, what grammar it speaks, how to describe it to developers and to agents, how an endpoint advertises what it serves, and how to reject a filter. Includes answers to the common questions.
- [Specification](https://openpredicate.tech/spec/): the normative document. Data model and field paths, three-valued logic, coercion, operator semantics, safety limits, error model, versioning.
- [Operator reference](https://openpredicate.tech/operators/): every operator, its operand shape and an example, generated from the schema.

## Artefacts

- [The JSON Schema](https://openpredicate.tech/schema/v0.4.0/open-predicate-schema.json): the grammar itself, served as `application/schema+json`. Self-contained — every `$ref` is internal.
- [Error conditions](https://openpredicate.tech/problems/): the five reasons a filter is rejected, each a dereferenceable RFC 9457 type URI.
- [Schema versions](https://openpredicate.tech/schema/): every published version, each immutable at its own URL.
- [Changelog](https://openpredicate.tech/changelog/): every release, with a migration note for each break.

## Optional

- [Playground](https://openpredicate.tech/playground/): validate a filter in the browser against the real grammar.
- [Full text](https://openpredicate.tech/llms-full.txt): the specification and operator reference as one markdown file.
- [Repository](https://github.com/OpenPredicate/open-predicate): source, issues and discussion.