🧩 JSON:API relfield

info

This extension is currently in draft state. We encourage you to participate in finalising this extension by providing your feedback at the extension's official repository

relfield

This extension provides query-syntax and -semantics for inclusion and exclusion of fields for requested resource objects.

Note: 
JSON:API defines itself to be always backwards compatible.For this reason, any mentioning of the JSON:API in this document won't refer to a specific version.

The following examples show unencoded [ and ] and : characters in query strings simply for readability. In practice, these characters must be percent-encoded, per the requirements in RFC 3986.

URI

This extension has the URI https://conjoon.org/json-api/ext/relfield.

Namespace

This extension uses the namespace relfield.

Note: JSON:API extensions can only introduce new document 
members using a reserved namespace as a prefix.

Example data for this document

This document uses the following data for demonstrating behavior specified by the JSON:API, and for demonstrating behavior introduced with this extension:

`article` Entity (type: `article`)

Field	Type	Description	Default	Optional
`id`	`integer`	The unique id of the article.	✔️
`title`	`string`	The title for the article.	✔️
`author`	`string`	The name of the article's author.	✔️
`date`	`string`	The date the article was edited.	✔️
`teaser`	`string`	A teaser text for the article.	✔️
`text`	`string`	The complete text of the article.	✔️
`version`	`string`	The article's version.		✔️
`secretfield`	`string`	A field with a value that is a mystery to everyone.		✔️

Sample Data

{
    "id": 1,
    "title": "Lorem ipsum",
    "author": "Jo Vongoe The",
    "date": "2022-06-25 18:00:00",
    "teaser": "Lorem ipsum dolor sit amet!"
    "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, [...]",
    "version": "v1.0",
    "secretfield": "?"
}

Endpoint

articles/{articleId}

Example for requesting an article with the id 1:

GET /articles/1 HTTP/1.1
Accept: application/vnd.api+json

Default fields for the `article` resource object

The endpoint defines the default fields returned with each article. If no fields[article] parameter was specified, the server guarantees to make the following fields available with a resource object of the type article:

title
author
date
teaser
text

Optional fields for the `article` resource object

The optional fields for the article resource object are

version
secretfield

An article resource object will only have the default fields and optional fields included with a response if the client requests them explicitly by using the fields[article] parameter:

GET /articles/1?fields[article]=title,author,date,teaser,text,version HTTP/1.1
Accept: application/vnd.api+json

gives the response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "data": {
        "id": 1,
        "type": "article",
        "attributes": {
            "title": "Lorem ipsum",
            "author": "Jo Vongoe The",
            "date": "2022-06-25 18:00:00",
            "teaser": "Lorem ipsum dolor sit amet!"
            "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, [...]",
            "version": "v1.0"
        }
    }
}

In this example, secretfield is not readable by the client. Trying to access it would result in a 403 Forbidden response:

GET /articles/1?fields[article]=secretfield HTTP/1.1
Accept: application/vnd.api+json

gives the response

HTTP/1.1 403 Forbidden
Content-Type: application/vnd.api+json

Sparse Fieldsets with the JSON:API as per specification

Clients MAY request that an endpoint includes only specific fields in the response in a per-type basis by including a fields[TYPE] parameter.

The following is specified:

If the client uses the fields[TYPE] parameter and leaves its value empty, the endpoint should not return any fields for resource objects with the given type in its response (please refer to this discussion for clarifications on the wording with this paragraph).
If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include any additional fields in resource objects of that type in its response.
If a client does not specify the set of fields for a given resource type, the server MAY send all fields, a subset of fields, or no fields for that resource type.

Sparse Fieldsets with the `relfied`-extension

This extension adds new semantics and syntax for querying fieldsets. It introduces two new characters as possible prefixes for fields:

+ (U+002B PLUS SIGN, “+”)
- (U+002D HYPHEN-MINUS, “-“)

When they are used as the first character in front of a field name provided with the relfield:fields[TYPE]-parameter, they describe additional (+) and excluded (-) fields.

This extension also introduces a wildcard character * (U+002A ASTERISK, “*”) for inclusion (*) of whole sets of fields of a resource.

Additional fields

Additional fields are fields that are added to the list of default fields that should be included with the response object, and prefixed with + (U+002B PLUS SIGN, “+”):

GET /articles/1?relfield:fields[article]=+version HTTP/1.1
Accept: application/vnd.api+json;ext=https://conjoon.org/json-api/ext/relfield

returns all the default fields, including the version field.

Excluded fields

Excluded fields are fields that should be excluded from the list of default fields returned with the response object and prefixed with - (U+002D HYPHEN-MINUS, “-“):

GET /articles/1?relfield:fields[article]=-text,-teaser HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

includes the default fields for the article resource object, without the fields text and teaser.

Wildcard Queries

The * (U+002A ASTERISK, “*”)-character serves as a wildcard for requesting all accessible fields - default and optional - for a specific resource type and serves mainly for reducing visual complexity of otherwise large queries.

GET /articles/1?relfield:fields[article]=* HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

returns the resource object with all (default & optional) fields available.

Wildcards represent all fields of a resource object. Additional fields specified with the query and mandatory prefixed with a + (U+002B PLUS SIGN, “+”) or - (U+002D HYPHEN-MINUS, “-“) are computed relative against the list of all (*) fields of a resource object. Thus, including a wildcard with a relfielf:fields[TYPE] query makes sense if the client wants to explixitly exclude fields.

Processing

There are no restrictions to the methods used with the HTTP requests sent with this extension.

If any operation in a request with this extension fails, the server MUST respond as described in the base specification of the JSON:API. An array of one or more error objects SHOULD be returned, each with a source member that contains a pointer to the source of the problem in the request document.

Compliance with base specifications for fieldsets

If a client uses the additional prefixes for identifying fields as additional + (U+002B PLUS SIGN, “+”) and/or excluded - (U+002D HYPHEN-MINUS, “-“) for the relfield:fields[TYPE] parameter, omitting such a character for any field-identifier MUST be responded with a 400 BAD REQUEST:

GET /articles/1?relfield:fields[article]=version,-title HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

responds with

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

Redundancy of fields

There is no specific treatment for

fields requested as additional, that are already part of the default list of fields of the resource object
fields requested as excluded, that are already missing from the default list of fields of the resource object

Mutual exclusivity of `relfield:fields[TYPE]`- and `fields[TYPE]`-parameter

If a client sends a request containing both relfield:fields[TYPE]- and fields[TYPE]-parameter, where TYPE refers to the same type of resource object, the server MUST respond with a 400 Bad Request.

If the client refers to different types of resource objects with TYPE and each fieldset specified with the query string, the server MUST treat the requested fieldsets as per their specifications.

Error Handling

The response SHOULD include a document with a top-level error member that contains one or more error objects providing further details on the fields that caused the error. If a prefix for a field is missing, this field SHOULD appear in the error object.

{
    "errors": [{
        "code": "123",
        "source": {"parameter": "relfield:fields[article]"},
        "title": "Bad Request",
        "detail": "Missing prefix for field 'version'."
    }]
}

Inaccessible fields

If the client requests an additional field that is not readable by the client, the server SHOULD respond with a 403 Forbidden. The response SHOULD include a document with a top-level error member that contains one or more error objects providing further details on the inaccessible field.
If the client issues a request that excludes a field that is usually not readable by the client, the server SHOULD treat the request as valid and proceed with its response according to its implementation. A 403 Forbidden response MAY be sent for very restrictive systems.

Examples

`article` includes all default fields and the `version` field

GET /articles/1?relfield:fields[article]=+version HTTP/1.1
Accept: application/vnd.api+json;ext=https://conjoon.org/json-api/ext/relfield

responds with

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

{
    "data": {
        "id": 1,
        "type": "article",
        "attributes": {
            "title": "Lorem ipsum",
            "author": "Jo Vongoe The",
            "date": "2022-06-25 18:00:00",
            "teaser": "Lorem ipsum dolor sit amet!"
            "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, [...]",
            "version": "v1.0"
        }
    }
}

Excluding `text` and `teaser` from the list of default fields of an `article`

GET /articles/1?relfield:fields[article]=-text,-teaser HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

responds with

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

{
    "data": {
        "id": 1,
        "type": "article",
        "attributes": {
            "title": "Lorem ipsum",
            "author": "Jo Vongoe The",
            "date": "2022-06-25 18:00:00",
        }
    }
}

Using sparse fieldsets with this extension for a different `TYPE`

GET /articles/1?relfield:fields[article]=+version&fields[comment]=author HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

In this example, the fields for article must be computed as per relfield specifications, and the fields for comment must be computed as per base specifications.

`400 Bad Request`: Using sparse fieldsets with this extension for the same `TYPE`

GET /articles/1?relfield:fields[article]=+version&fields[article]=title HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

MUST respond with

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

`400 Bad Request`: Omitting prefixes with this extension for field values

GET /articles/1?relfield:fields[article]=version,-title HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

MUST respond with

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

Requesting fields with inaccessible fields excluded

The client issues a request that excludes secretfield, which is not redable for the client.

GET /articles/1?relfield:fields[article]=-secretfield HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

SHOULD respond with

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

`403 Bad Request`: Requesting inaccessible fields

The client requests secretfield, which is not readable for this client:

GET /articles/1?relfield:fields[article]=+secretfield HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

SHOULD respond with

HTTP/1.1 403 Forbidden
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

and SHOULD include

{
    "errors": [{
        "code": "123",
        "source": {"pointer": "/data/attributes/secretfield"},
        "title": "Access forbidden",
        "detail": "secretfield may not be accessed."
    }]
}

Wildcard Queries

Requesting all fields for an `article`

GET /articles/1?relfield:fields[article]=* HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

SHOULD respond with

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

{
    "data": {
        "id": 1,
        "type": "article",
        "attributes": {
            "title": "Lorem ipsum",
            "author": "Jo Vongoe The",
            "date": "2022-06-25 18:00:00",
            "teaser": "Lorem ipsum dolor sit amet!"
            "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, [...]",
            "version": "1.0"
        }
    }
}

Requesting all fields for an `article`, excluding `version` and `teaser`

GET /articles/1?relfield:fields[article]=*,-version,-teaser HTTP/1.1
Accept: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

responds with

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://conjoon.org/json-api/ext/relfield"

{
    "data": {
        "id": 1,
        "type": "article",
        "attributes": {
            "title": "Lorem ipsum",
            "author": "Jo Vongoe The",
            "date": "2022-06-25 18:00:00",      
            "text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit, [...]"
        }
    }
}

Similar API implementations

The bitbucket API of Atlassian provides similar behavior with their use of the fields paramter with partial responses.

info

relfield

URI​

Namespace​

Example data for this document​

article Entity (type: article)​

Sample Data​

Endpoint​

Default fields for the article resource object​

Optional fields for the article resource object​

Sparse Fieldsets with the JSON:API as per specification​

Sparse Fieldsets with the relfied-extension​

Additional fields​

Excluded fields​

Wildcard Queries​

Processing​

Compliance with base specifications for fieldsets​

Redundancy of fields​

Mutual exclusivity of relfield:fields[TYPE]- and fields[TYPE]-parameter​

Error Handling​

Inaccessible fields​

Examples​

article includes all default fields and the version field​

Excluding text and teaser from the list of default fields of an article​

Using sparse fieldsets with this extension for a different TYPE​

400 Bad Request: Using sparse fieldsets with this extension for the same TYPE​

400 Bad Request: Omitting prefixes with this extension for field values​

Requesting fields with inaccessible fields excluded​

403 Bad Request: Requesting inaccessible fields​

Wildcard Queries​

Requesting all fields for an article​

Requesting all fields for an article, excluding version and teaser​

Similar API implementations​

URI

Namespace

Example data for this document

`article` Entity (type: `article`)

Sample Data

Endpoint

Default fields for the `article` resource object

Optional fields for the `article` resource object

Sparse Fieldsets with the JSON:API as per specification

Sparse Fieldsets with the `relfied`-extension

Additional fields

Excluded fields

Wildcard Queries

Processing

Compliance with base specifications for fieldsets

Redundancy of fields

Mutual exclusivity of `relfield:fields[TYPE]`- and `fields[TYPE]`-parameter

Error Handling

Inaccessible fields

Examples

`article` includes all default fields and the `version` field

Excluding `text` and `teaser` from the list of default fields of an `article`

Using sparse fieldsets with this extension for a different `TYPE`

`400 Bad Request`: Using sparse fieldsets with this extension for the same `TYPE`

`400 Bad Request`: Omitting prefixes with this extension for field values

Requesting fields with inaccessible fields excluded

`403 Bad Request`: Requesting inaccessible fields

Wildcard Queries

Requesting all fields for an `article`

Requesting all fields for an `article`, excluding `version` and `teaser`

Similar API implementations