An open standard for JSON-encoded predicates.

Search endpoints attract bespoke query syntaxes. Each one arrives as an opaque string parameter — ?q=status:open AND born>2020 — that no schema can validate, no generator can type, and no client can build safely. OpenPredicate structures the predicate as JSON and describes it with a single JSON Schema, so one grammar can serve every POST /…/search, every QUERY /…, and every search tool you hand an agent.

{
  "$and": [
    { "status": "available" },
    { "$or": [
        { "species": { "$in": ["cat", "dog"] } },
        { "tags":    { "$some": { "$in": ["rescue", "senior"] } } }
    ]},
    { "born": { "$gte": "2020-01-01" } }
  ]
}

One schema, two integration points, because JSON Schema is what both already speak: it is the interchange format of OpenAPI 3.1, and it is what an MCP tool's inputSchema is.

To take a predicate grammar from a single-author design to an open standard, and to push for its adoption at the places APIs are already described — $ref-ed from OpenAPI documents, inlined as MCP tool schemas, and carried as the body of the HTTP QUERY method.

That goal sets the terms of the work:

• The grammar is specified normatively, in SPEC.md, rather than left to a reference implementation — so independent implementations can actually agree. Nulls, paths, coercion, three-valued logic, safety limits and the error model are all pinned down.
• Servers declare what they cannot do. Operators are grouped into profiles, and a server publishes a capability document. Implementing a subset honestly beats silently mistranslating.
• Every breaking change carries a migration note, in CHANGELOG.md. Pre-1.0, that is the deal in exchange for the version number.
• Design decisions are argued in writing, under decisions/, rather than settled by commit.
• The case for adoption is made in the open, including its gaps — COMPARISON.md is where OpenPredicate is compared with GraphQL and where what it does not do is admitted.

Pre-1.0. The grammar, the operator set and profile grouping, the null and three-valued semantics, and the error model are stable enough to build against. Packages are not yet published to a registry — pin the versioned $id, or vendor the schema file.

Disagreement is the most useful contribution at this stage. If the grammar is wrong, or a semantic is under-specified, or an operator is missing something a real backend needs — open an issue.

Everything is MIT-licensed, so the grammar can be implemented, vendored, extended and re-specified without permission.

📬 contact@openpredicate.tech