# Agility query grammars (vendored)

These three ANTLR v3 grammar files are copied **verbatim** from
versionone/Grammars. They are
published here so that the formal syntax of the `rest-1.v1` query string is
available as a machine-readable artifact alongside the human-readable
reference.

| File                | Covers                                                         |
| ------------------- | -------------------------------------------------------------- |
| `V1Query.g`         | Attribute selection, attribute paths, filter expressions, sort |
| `V1FilterContext.g` | The `with` parameter (variable assignment)                     |
| `V1Paging.g`        | The `page` parameter                                           |

They are licensed under a modified BSD license; the license header comment at
the top of each file is intact and must be preserved.

## Caveats

The grammars were last revised in 2012 and the upstream project states that
they describe the intended syntax rather than the shipped implementation. Where
the grammar and the Agility server disagree, the server wins. The differences
that are currently known are catalogued in the human-readable reference:

https://docs.digital.ai/agility-api/reference/query-grammar

In particular, `V1Query.g` names its filter root rule `filter2_token`, which has
repeatedly been misread as implying a `filter=` query parameter. There is no
`filter` query parameter on `rest-1.v1`; the wire parameter is `where`.