One maintainer, no service-level agreement. Everything here is best-effort, usually within a week. Knowing that up front is more useful than a promise that does not hold.
| You want to | Go to |
|---|---|
| Try a filter and see it validate | The playground — runs the real schema in your browser and shows the error a conforming server would return |
| Know what an operator means, normatively | SPEC.md, or the generated operator reference |
| Ask how to do something | Discussions → Q&A |
| Argue that a design decision is wrong | An issue, using the design objection template — see CONTRIBUTING.md |
| Report that the schema and the spec disagree | An issue, using the spec ambiguity template |
| Report a security or denial-of-service concern | SECURITY.md — not a public issue |
| Say you have implemented it | An issue, using the implementation report template. These are the most welcome issues the project receives |
| Understand why a decision was made | decisions/ and CHANGELOG.md, which carries a migration note for every break |
| Know how this compares to GraphQL, OData, CQL2, Mongo or JSONPath | COMPARISON.md, including the gaps it admits |
Three things surprise almost everyone, and all three are deliberate:
- Sibling members AND together, and a bare scalar means
$eq.{"status": "open", "rank": 3}isstatus = 'open' AND rank = 3. You only need$andto repeat a field, or to nest inside$or. - A comparison against
nullor an absent field is UNKNOWN, not FALSE — and only TRUE matches. So{"status": {"$ne": "archived"}}does not match a record whose status is missing. That is SQL's behaviour. When you want those records, say so:{"$ne": "archived", "$unknownAs": true}. $indoes not look inside arrays. It is whole-value comparison. Element membership is{"tags": {"$some": {"$in": [...]}}}. This differs from MongoDB on purpose — overloading$inmakes the meaning depend on data a validator cannot see.
Pre-1.0: only the latest release is supported, and the grammar may still break before 1.0. Pin an
exact version if you depend on it. The schema $id is versioned and immutable — v0.4.0 will always
return the bytes it returned the day it was published — so $ref-ing a versioned $id is the
safe thing to do. There is deliberately no latest URL.