JSON Resource Query Language, for simple, consistent query APIs
json-rql is a convention for expressing queries against structured resources, using JSON. It helps resolve the tensions between expressibility and simplicity, and between agility and future-proofing, in API design. It is based on JSON-LD.
A simple example query:
{ "@where" : { "@type" : "Person", "birthPlace" : { "name": { "@contains" : "London" } } } }
See the project wiki for more discussion of the motivation behind json-rql.
Here we describe the syntax of json-rql informally in terms of JSON constructs (hashes and keys), for introductory purposes. The type definitions below and in the navigation panel on the left gives a more formal specification.
Hint: links are provided from keywords to examples. Note that these are rather SPARQL-ish, in that they make extensive use of prefixes and IRIs. An API doesn't have to use these much, if at all. Also linked in the formal type documentation are various SPARQL and JSON-LD definitions. Again, you generally don't have to follow these links to be able to use json-rql effectively; the examples given should be sufficiently explanatory.
All json-rql queries are an object/hash at top level (one of the sub-types
of Pattern). All the recognised keys of this hash are keywords, which start with
a @
. However, any other keys can exist as required by the API design, such as
a name or description for the query.
The recognised query keys are:
@context
:
A JSON-LD Context for
the query. In an API this is likely to be implicit. For example, using
json-rql as the body of a POST
to
http://example.com/my-api/v1/person/query
might have the implicit context
of a Person (possibly found at http://example.com/my-api/v1/person
). As a
user of the API, therefore, you may not need to consider the Context.@construct
specifies a Subject for the requested data,
using Variables to place-hold data matched by the @where
clause.@describe
specifies an IRI, a Variable, or an array of either. Each
matched value will be output in some suitable expanded format, such as an
entity with its top-level properties.@select
specifies a Result, which defines a set of outputs. The output
will be a table of atomic values.@distinct
is like @select
but returns only unique rows.@where
specifies a Pattern to match, or an array of
Patterns to match. Each can be a Subject, a
Group, or another query (a sub-query).@orderBy
specifies an Expression or array of expressions to order the results by.@groupBy
specifies an Expression or an array of expressions to group
the result by.@having
specifies an Expression to filter individual grouped-by
members.@values
specifies a Variable Expression or
array of Variable Expressions that define inline allowable value combinations
for the query variables.@limit
and @offset
specify integer paging for the results.This is a JSON-LD object with the following non-compliances:
"?variable"
.{ <operator> : <Expression> }
.
The operator is acting as an infix, and in this case the
Expression represents only the RHS. The object may specify a variable to be
matched against the filter by including an @id
key as well as the operator,
like this: { "@id" : "?variable", <operator> : <Expression> }
.A Group object has one or more of the following keys:
@graph
specifies a Subject or an array of Subjects to match.@filter
specifies a Constraint or an array of
Constraints, each of the form { <operator> : [<Expression>...] }
. Note that
filters can also be specified in-line inside a Subject, see above.@union
specifies an array of alternative Patterns (Subject, Group or query) to
match.@optional
specifies a Group that may or may not match.An Expression can be
"?variable"
,{ <operator> : [<Expression>...] }
.
The key is the operator, and the value is the array of
arguments. If the operator is unary, the Expression need not be wrapped in an
array.A variable Expression is either a plain variable (e.g. "?size"
), or an object
whose keys are variables, and whose values are expressions whose result will be
assigned to the variable, e.g.
{ "?averageSize" : { "@avg" : "?size" } }
Used to express an ordered or unordered container of data.
A stand-in for a Value used as a basis for filtering. An expression can be
"?variable"
,{ <operator> : [<expression>...] }
.An in-line filter, of the form { <operator> : <expression> }
. The operator
is acting as an infix, and in this case the expression represents only the
RHS. The object may specify a variable to be matched against the filter by
including an @id
key as well as the operator, like this:
{ "@id" : "?variable", <operator> : <expression> }
.
A node object used to reference a node having only the @id
key.
The allowable types for a Subject property value, named awkwardly to avoid
overloading Object
. Represents the "object" of a property, in the sense of
the object of discourse, whether it be a concrete value or a filter.
A term definition is an entry in a context, where the key defines a term which may be used within a JSON object as a property, type, or elsewhere that a string is interpreted as a vocabulary item. Its value is either a string (simple term definition), expanding to an absolute IRI, or an expanded term definition.
A value that can be assigned as the target of a graph edge.
A query variable, prefixed with "?"
Like a Reference, but used for "vocabulary" references. These are relevant to:
@type
: the type value is a vocabulary reference@vocab
in the ContextDetermines whether the given property object from a well-formed Subject is a
graph edge; i.e. not a @context
or the Subject @id
.
the Subject property in question
the object (value) of the property
Determines if a Pattern can be used as a top-level object to perform a write against a data set. A writeable Pattern can be:
@graph
key, containing writeable SubjectsThis check does not guarantee that any updates will actually be made. It also leaves a class of Patterns that are neither Reads nor Writeable. Such patterns should not be accepted by a data store as a transaction.
An implementation may wish to leave the scan for variables until query processing, for efficiency; if so, pass the 'quick' parameter.
Generated using TypeDoc. Delivered by Vercel. json-rql - v0.6.2 Source code licensed MIT. Privacy policy
A basic atomic value used as a concrete value or in a filter.