v0.3.1 — a release that publishes nothing

0.3.1 is the release 0.3.0 never became: the 0.3.0 tag was cut against a pipeline that still published to npmjs.com and GitHub Packages, and this project ships no artifacts while its name is a working title. The notes below therefore cover both versions.

Nothing here is downloadable but the source. To use the schema, vendor it:

curl -O https://raw.githubusercontent.com/christosgkoros/json-query-language/v0.3.1/query-language-schema.json

---

[0.3.1] — 2026-09-04

No change to the schema, the grammar or the semantics. query-language-schema.json is
byte-identical to 0.3.0 and its $id still names v0.3.0, because the $id version tracks the
grammar and the grammar did not move. Consumers pinning that $id have nothing to do.

Removed

• Publishing. The release workflow no longer ships to npmjs.com or GitHub Packages. Neither
  registry ever received a copy, and while the name is a working title neither should: publishing
  under a placeholder claims the name, and npm blocks a name from reuse permanently once it has
  been published and unpublished. .github/workflows/release.yml now only verifies a release —
  the test suite, and the tag-against-package.json check — and uploads nothing. The
  NPM_TOKEN secret and .github/scripts/version-published.sh are deleted with it.
  RELEASING.md keeps what the jobs needed, so they
  can be restored from git history rather than rewritten.

Changed

• README no longer offers an install that does not exist. The Quickstart opened with
  npm install --save-dev json-query-language, which the README's own Status table already
  contradicted two screens further down. It now vendors the file by curl, which is the only
  way to obtain the schema and always was.
• RELEASING.md documents the process that exists — a tag and a GitHub
  Release, carrying notes and a source snapshot and nothing else.

[0.3.0] — 2026-09-04

Guidance for adopters exposing a search endpoint to an LLM agent, the tooling that acts on it,
and an honest statement of how finished this is. No grammar change: every filter valid under
v0.2.0 remains valid, and the only edits to query-language-schema.json are two description
annotations and its version strings.

Added

• Per-field domains in the capability document. SPEC.md §2.2's
  RECOMMENDED shape now carries type, format, values and description alongside
  operators, with a table defining each. The grammar cannot express per-field operand
  domains — every path shares one Constraint — so a filter naming a real field with an
  out-of-domain value is well-formed and matches nothing. The capability document is the only
  place that domain can be stated.

• Recovery members on problem details. SPEC.md §8 now RECOMMENDS that
  unknown-field carry queryableFields and that invalid-operand carry accepted, so a
  client that never fetched the capability document can still converge in one round trip
  instead of guessing field names one at a time.

• README §Exposing search to an agent — what reaches a tool definition, the three
  valid-but-wrong filters that fail as an empty result set, and the five steps that prevent
  them (bundle rather than remote-$ref, narrow FieldPath, publish value domains, trim to
  advertised profiles, state the null and $in semantics in the tool description).

• tools/generate-filter-schema.mjs — derives a per-resource filter schema from the
  resource's own JSON Schema. The published grammar shares one Constraint across every field,
  so it can say {"status": "Available"} is well-formed but not that "Available" is outside
  status's domain; that is why SPEC.md §2.2 exists. A
  generated schema gives each queryable path its own constraint subschema, carrying only the
  operators that apply to its type and only the operands its domain admits — so the three
  valid-but-wrong filters catalogued in README §Exposing search to an agent become validation
  failures instead of empty result sets. The generator emits the §2.2 capability document from
  the same source, and copies operator prose out of the published grammar rather than restating
  it. Generation is narrowing only: every filter a generated schema accepts is valid against the
  published grammar, which tests/generator.test.mjs asserts.

• COMPARISON.md — how this specification relates to GraphQL, and what a JSON-Schema-native
  alternative to GraphQL would still need. The short version: GraphQL never standardised
  filtering, so the two overlap far less than the question assumes. Also covers OData, JSON:API,
  OGC CQL2 and JSON Hyper-Schema as prior art.

• examples/pet.schema.json with its generated pet.filter.json and pet.capabilities.json
  committed beside it, and npm run generate:example to refresh them. A test fails if they drift.

• README §Generating a per-resource filter schema — what the generator decides and why, and
  the x-jql property annotations that override it.

Changed

• README framing. The schema is presented as feeding two integration paths rather than
  one: $ref'd from an OpenAPI document, or bundled into an MCP tool's inputSchema. The
  Referencing by URL or by copy table gains an MCP inputSchema row recording that the
  absolute-URL form does not work there at all, since nothing on that path resolves remote
  refs.
• $in and $nin descriptions now state that they compare the whole value and do not test
  array membership, naming $hasAny/$hasNone as the element operators. $contains already
  warned about the same crossover; these two did not, and they are the operators a client
  carrying MongoDB habits reaches for first.
• $id is now …/v0.3.0/query-language-schema.json. Consumers pin by $id, so the version
  in the path moves with the release. SPEC.md, the OpenAPI examples and the generated
  capability document were all still naming v0.2.0; they now agree.
• README §Status states that this is a work in progress, name included. JSON Query
  Language is a working title, and every identifier downstream of it — both package names, the
  $id, the URLs in the integration examples — is a placeholder, several of which do not
  resolve. Getting them right is deliberately deferred until the name is settled, because a
  rename moves all of them at once. A notice at the top of the README says the same thing before
  a reader reaches an install command that will not work.
• QUERY now cites RFC 10008 rather than
  draft-ietf-httpbis-safe-method-w-body. The method reached Proposed Standard in June 2026.
  The advice to ship POST /search alongside it is unchanged, but the reason is now that
  deployed support trails a fresh RFC, not that the specification is unsettled.