<commit_before>---
layout: page
title: "JSON API: Format"
---

{% include status.md %}

## Document

In this specification, the term "document" refers to a single object with a
set of attributes and relationships.

A JSON response may include multiple documents, as described in this
specification.

### Top Level

The top-level of a JSON response will contain the primary document(s)
keyed by the plural form of the primary resource type.

The top-level of the JSON response **MAY** also have the following keys:

* `"meta"`: meta-information about a resource, such as pagination.
* `"links"`: URL templates to be used for expanding resources' relationships
  URLs.
* `"linked"`: a collection of documents, grouped by type, that are related to
  the primary document(s) and/or each other.

Each of these keys has a special meaning when included in the top level and
should not be used as a resource type in order to avoid conflicts.

No other keys should be present at the top level of the JSON response.

### Singular Resources

Documents that represent singular resources are wrapped inside an array
and keyed by the plural form of the resource type:

```javascript
{
  "posts": [{
    "id": 1
    // an individual post document
  }]
}
```

This simplifies processing, as you can know that documents will always be
wrapped in arrays.

The document **SHOULD** contain an `"id"` key.

### Resource Collections

Documents that represent resource collections are also wrapped inside an array
and keyed by the plural form of the resource type:

```javascript
{
  "posts": [{
    "id": 1
    // an individual post document
  }, {
    "id": 2
    // an individual post document
  }]
}
```

Each document in the array **SHOULD** contain an `"id"` key.

### IDs

The `"id"` key in a document represents a unique identifier for the underlying
resource, scoped to its type. It can be used with URL templates to fetch related
resources, as described below.

In scenarios where uniquely identifying information between client and server
is unnecessary (e.g., read-only, transient entities), JSON API allows for
omitting the `"id"` key.

NOTE: While an implementation could use the values of `"id"` keys as URLs
(which are unique string identifiers, after all), it is not generally
recommended. URLs can change, so they are unreliable for mapping a document to
any client-side models that represent the same resource. It is recommended that
URL values be left to the task of linking documents while `"id"` values remain
opaque to solely provide a unique identity within some type.

### Attributes

There are three reserved attribute names in JSON API:

* `id`
* `href`
* `links`

Every other key in a document represents an attribute. An attribute's value may
be any JSON value.

```javascript
{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase"
  }]
}
```

### Relationships

The value of the `"links"` key is a JSON object that represents related
resources.

```javascript
{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "5", "12", "17", "20" ]
    }
  }]
}
```

The link to each related resource **MUST** be one of the following:

* a string or number - to represent a single ID.
* an array of strings or numbers - to represent multiple IDs.
* an object that contains one or more of the attributes:
  `"id"`, `"ids"`, `"href"` and `"type"`. Note that `"id"` and `"ids"` should
  never be present together.

NOTE: Use of a document level `"links"` object is generally discouraged because
root level URL Templates can usually provide the same data more concisely.
However, there may be situations where each document will have a URL that isn't
supported by the rigid structure of a template. In those cases, it may also be
necessary to include either `"id"` or `"ids"` for the related documents in a
compound document.<commit_msg>Define "link" objects in Relationships section<commit_after>---
layout: page
title: "JSON API: Format"
---

{% include status.md %}

## Document

In this specification, the term "document" refers to a single object with a
set of attributes and relationships.

A JSON response may include multiple documents, as described in this
specification.

### Top Level

The top-level of a JSON response will contain the primary document(s)
keyed by the plural form of the primary resource type.

The top-level of the JSON response **MAY** also have the following keys:

* `"meta"`: meta-information about a resource, such as pagination.
* `"links"`: URL templates to be used for expanding resources' relationships
  URLs.
* `"linked"`: a collection of documents, grouped by type, that are related to
  the primary document(s) and/or each other.

Each of these keys has a special meaning when included in the top level and
should not be used as a resource type in order to avoid conflicts.

No other keys should be present at the top level of the JSON response.

### Singular Resources

Documents that represent singular resources are wrapped inside an array
and keyed by the plural form of the resource type:

```javascript
{
  "posts": [{
    "id": 1
    // an individual post document
  }]
}
```

This simplifies processing, as you can know that documents will always be
wrapped in arrays.

The document **SHOULD** contain an `"id"` key.

### Resource Collections

Documents that represent resource collections are also wrapped inside an array
and keyed by the plural form of the resource type:

```javascript
{
  "posts": [{
    "id": 1
    // an individual post document
  }, {
    "id": 2
    // an individual post document
  }]
}
```

Each document in the array **SHOULD** contain an `"id"` key.

### IDs

The `"id"` key in a document represents a unique identifier for the underlying
resource, scoped to its type. It can be used with URL templates to fetch related
resources, as described below.

In scenarios where uniquely identifying information between client and server
is unnecessary (e.g., read-only, transient entities), JSON API allows for
omitting the `"id"` key.

NOTE: While an implementation could use the values of `"id"` keys as URLs
(which are unique string identifiers, after all), it is not generally
recommended. URLs can change, so they are unreliable for mapping a document to
any client-side models that represent the same resource. It is recommended that
URL values be left to the task of linking documents while `"id"` values remain
opaque to solely provide a unique identity within some type.

### Attributes

There are three reserved attribute names in JSON API:

* `id`
* `href`
* `links`

Every other key in a document represents an attribute. An attribute's value may
be any JSON value.

```javascript
{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase"
  }]
}
```

### Relationships

The value of the `"links"` key is a JSON object that represents related
resources.

```javascript
{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "5", "12", "17", "20" ]
    }
  }]
}
```

The link to each related resource **MUST** be one of the following:

* a string or number - to represent a single ID.
* an array of strings or numbers - to represent multiple IDs.
* a "link" object that contains one or more of the attributes:
  `"id"`, `"ids"`, `"href"` and `"type"`. Note that `"id"` and `"ids"` should
  never be present together.
* an array of "link" objects

NOTE: Use of a document level `"links"` object is generally discouraged because
root level URL Templates can usually provide the same data more concisely.
However, there may be situations where each document will have a URL that isn't
supported by the rigid structure of a template. In those cases, it may also be
necessary to include either `"id"` or `"ids"` for the related documents in a
compound document.
{'fraction_non_alphanumeric': 0.09055118110236221, 'fraction_numerical': 0.003302006604013208, 'mean_word_length': 3.912663755458515, 'pattern_counts': {'":': 28, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5125735', 'n_tokens_mistral': 2190, 'n_tokens_neox': 2097, 'n_words': 1162}