# Status

This extension was developed as part of the [jsonapi module for Drupal](https://drupal.org/project/jsonapi).

# Introduction

The [JSON API](http://jsonapi.org/format/#fetching-filtering) specification is agnostic about how a server implements filtering strategies. In fact, the spec says:

> Note: JSON API is agnostic about the strategies supported by a server. The `filter` query parameter can be used as the basis for any number of filtering strategies.

This specification covers the gap by specifying an strategy that can be adopted by any JSON API server. This specification will cover:
  * Filter conditions: These are the assertions made against the data store which qualify a record for inclusion in a collection result.
  * Filter groups.: These allow the creation of complex, nested queries. For example, queries with AND operators within a higher level OR condition.

# Filter Conditions

Filter conditions are represented by _conditional objects_. These object codify a conditional statement that a JSON API server will execute in order to retrieve a subset of eligible records. These are called _where_ clauses in many data query languages, like SQL.

A conditional object **MUST** have an arbitrary ID which uniquely idenfies the conditional object inside of the `filter` parameter of a JSON API request URI. Additionally, a conditional object **MUST** contain the following keys:

  * `path`. The path property **MUST** adhere to the _property accessor format_. The `path` identifies the property within the entity type that hosts it. The path selects the data value against which the conditional object will be applied. A path **MUST** be able to select any attribute property of an entity. A path **MAY** be able to traverse relationships.
  * `value`. The value used in the comparison made against the data value of the property identified by the `path`.

A conditional object **MAY** also contain the following keys:

  * `operator`. The operator used during the comparison. If nothing is specified, then the operator defaults to `'='`. A JSON API server **SHOULD** implement, at least, the following operators: `=`, `<`, `>`, `<>`. In addition to those operators, a server **MAY** support `IN`, `NOT IN`, `BETWEEN`, `IS NULL` and `IS NOT NULL`.
  * `memberOf`. If the conditional object should be grouped within a parent group object, this should  be that group object's arbitrary ID. If the contents of the `memberOf` property does not match any group definition ID, then the conditional object **MAY** be ignored. If this property is not provided, then the current condition **SHOULD** be assigned to the implicit _root group_.

In conditionals with operators that act on multiple values (like `IN`), the `value` property **MUST** hold an array of values.

The keys for a filter conditional **MUST** be wrapped in a `condition` property to specify that the arbitrary ID is for a condition.

## Property Accessor Format

A _property accessor_ is used to identify a property or sub-property in the requested entity type, or, if the server supports it, any entity type accessible via relationships from the requested entity type. _Property accessors_ **MUST** contain be a dot separated list of path elements. Each path element **MUST** be an attribute field or the name of a property in an attribute. If the JSON API server support conditions which traverse relationship, the _property accessor_ **MAY** contain relationship names as path elements. The last path element of the _property accessor_ **MUST** be an attribute followed by an optional group attribute's property names.

### Example 1

In the simplest form, the _property accessor_ is just the name of the attribute. For example, the _propery accessor_ for the title attribute of a `blog` entity would simply be: `title`

### Example 2

In a more complex form, you may wish to filter based on attributes accessed across a relationship. For example, you wish to get all post created by authors whose accounts were created within the last week. There exists an entity type, `blog`, and an entity type `user`. The `blog` type has a relationship to its creating user under the `author` relationship. The `user` entity type has an attribute of `created` representing the date that the user account was established. Thus, the _property accessor_ is simply: `author.created`

### Example 3

You want to get all TV shows, that contain a published video in a given streaming platform ("netflix"). Assume that there is an object attribute inside of the `/videos` resource that contains a list of streaming platforms as keys with a boolean as values.

In this case, the _property accessor_ would be: `seasons.videos.published.netflix`. Where `seasons` and `videos` are relationships, `published` is an attribute in the videos entity type and `netflix` is a property inside of the `published` attribute.

### Example 4

If property `prop` inside of the attribute `attr`, belonging to the entity type `C` wants to be used to include/exclude records in the resource `A`. Then there must be a relationship, or a chain of relationships, between entity type `A` and `C`. In this example, assume that there is a relationship `relAtoB` that goes from `A` to `B`, and relationship `relBtoC` that goes from `B` to `C`. In this scenario the _property accessor_ will be: `relAtoB.relBtoC.attr.prop`.

# Filter Groups

A group objecst are used to evaluate multiple conditions or other groups in tandem. They provide the ability to specify a conjunction between multiple conditional objects and/or group objects.

A group object **MUST** have an arbitrary ID that uniquely idenfies the group object inside of the `filter` parameter in the JSON API request URI. Additionally a group object **MUST** contain the following keys:

  * `conjunction`. A JSON API server **MUST** support `AND` and `OR`. A server **MAY** support any of: `NAND`, `NOR`, `XOR`, `XNOR` and other binary logical operators.
  * `memberOf`. The result of a group might need to be evaluated inside of a group with other groups and/or conditions. To specify the group this current group belongs to, the `memberOf` key **MUST** be used.

If no group is specified, a JSON API server **MUST** assume that all the conditional objects belong to a single implicit _root group_.

The keys for a filter conditional **MUST** be wrapped in a `group` property to specify that the arbitrary ID is for a group.

## Implicit Root Group

Filter and group objects may omit the `memberOf` keys. In this case, a server **MUST** assume that these objects belong to an implicit _root group_. The JSON API **MUST** use the `AND` conjuntion for this _root group_.

# Examples

## Example 1

You want to get all TV shows, that contain a published video in "netflix" or in "hulu". The equivalent filter object shuold be:

  * `orGroup`. A group with the or conjunction for the two conditions.
  * `hasNetflix`. A condition for the netflix published flag.
  * `hasHulu`. A condition for the hulu published flag.
  * `tags`. A condition for the tags on the TV show seasons.

That translates to:

```yaml
filter:
  orGroup:
    group:
      conjunction: OR
  hasNetflix:
    condition:
      path: seasons.videos.published.netflix
      value: true
      memberOf: orGroup
  hasHulu:
    condition:
      path: seasons.videos.published.hulu
      value: true
      memberOf: orGroup
  tags:
    condition:
      path: seasons.tags
      value:
        - awesome
        - great
      operator: IN
```

Serializing the `filter` object according to [RFC 3986](https://tools.ietf.org/html/rfc3986), results in a request like:

```http
GET /api/shows?filter[orGroup][group][conjunction]=OR&filter[hasNetflix][condition][path]=seasons.videos.published.netflix&filter[hasNetflix][condition][value]=1&filter[hasNetflix][condition][memberOf]=orGroup&filter[hasHulu][condition][path]=seasons.videos.published.hulu&filter[hasHulu][condition][value]=1&filter[hasHulu][condition][memberOf]=orGroup&filter[tags][condition][path]=seasons.tags&filter[tags][condition][value][]=awesome&filter[tags][condition][value][]=great&filter[tags][condition][operator]=IN HTTP/1.1
Host: example.com
Content-Type: application/vnd.api+json; ext=fancyfilters
Accept: application/vnd.api+json; ext=fancyfilters
```