# Pagination and Error Source spec compliance
**URL:** https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077
**Category:** Uncategorized
**Created:** [October 20, 2020, 2:10pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077 "2020-10-20T14:10:16Z")
**Posts on this page:** 13
**Page:** 1
### Author:  [@bokara](https://discuss.jsonapi.org/u/bokara)
#### Post date: [October 20, 2020, 2:10pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/1 "2020-10-20T14:10:17Z")
Hi,
after reading [#851](https://github.com/json-api/json-api/issues/851), [#147](https://discuss.jsonapi.org/t/how-to-validate-the-json-api-format/147) etc, I understood that
> Unless otherwise noted, objects defined by this specification **MUST NOT** contain any additional members. Client and server implementations **MUST** ignore members not recognized by this specification.
> This [schema](http://jsonapi.org/schema) is as restrictive as possible, but has flexibility to be extended within your documentation. Validation will not yield false negatives, but **could yield false positives** for the sake of flexibility.
so to confirm, for **Pagination** links
the spec said:
> The following keys **MUST** be used for pagination links:
>
> - `first` : the first page of data
> - `last` : the last page of data
> - `prev` : the previous page of data
> - `next` : the next page of data
But something like the following could pass the validation
```auto
"links": {
"next": "http://xxx/2",
"otherLinks": {
"3": "http://xxx/3",
"4": "http://xxx/4"
}
}
```
Questions:
1. can Pagination have keys other than ‘first’, ‘last’, ‘prev’, ‘next’ to be regarded as compliant with the spec (or media type ‘application/vnd.api+json’)?
2. similarly, can Error **Source** property have keys other than ‘pointer’ and ‘parameter’? (e.g., other keys like ‘header’)
---
### Author:  [@claudenirmf](https://discuss.jsonapi.org/u/claudenirmf)
#### Post date: [October 21, 2020, 4:28pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/2 "2020-10-21T16:28:26Z")
Hi @bokara,
> A server **MAY** provide links to traverse a paginated data set (“pagination links”).
This is why the case above passes the validation, you are not required to always have these links in your message. However…
> The following keys **MUST** be used for pagination links:
>
> - `first` : the first page of data
> - `last` : the last page of data
> - `prev` : the previous page of data
> - `next` : the next page of data
The schema cannot valid the constraint above, as it refers to how to use these labels (i.e., “first”, “last”, “prev”, and “next”). The only thing the schema can do is to check if these labels/fields are assigned to `null` or a URL string whenever they are present.
Other than that, you may implement the standard adding links other than the ones listed (for pagination or anything else that suits the purpose of the “links” object).
> similarly, can Error **Source** property have keys other than ‘pointer’ and ‘parameter’? (e.g., other keys like ‘header’)
About this
> An error object **MAY** have the following members:
> `source` : an object containing references to the source of the error, optionally including any of the following members:
>
> - `pointer` : a JSON Pointer [[RFC6901](https://tools.ietf.org/html/rfc6901)] to the associated entity in the request document [e.g. `"/data"` for a primary data object, or `"/data/attributes/title"` for a specific attribute].
> - `parameter` : a string indicating which URI query parameter caused the error.
These are **MAY** conditions. You can implement these things however you so desire. I only recommend you to local around how people usually solve these problems so you avoid making bad design decisions.
P.s.: you could enjoy having a look at this [here](https://jsonapi.org/format/#conventions):
> Conventions
> The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 [[RFC2119](http://tools.ietf.org/html/rfc2119)].
---
### Author:  [@bokara](https://discuss.jsonapi.org/u/bokara)
#### Post date: [October 21, 2020, 7:44pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/3 "2020-10-21T19:44:33Z")
@claudenirmf,
Thank you for the detailed and helpful response; greatly appreciated.
I would like to confirm about the **links** example in the original post (to help me better understand the spec)
- technically, that should still fail the validation? because the **otherLinks** is not a valid **link** object?
i.e.,
This is VALID,
```auto
"links": {
"next": "http://xxx/2",
"otherLinks": {
"href": "http://xxx/3"
}
}
```
or this is also VALID:
```auto
"links": {
"next": "http://xxx/2",
"3": "http://xxx/3",
"4": "http://xxx/4"
}
```
But this is INVALID?
```auto
"links": {
"next": "http://xxx/2",
"otherLinks": {
"3": "http://xxx/3",
"4": "http://xxx/4"
}
}
```
would that be correct?
---
### Author:  [@claudenirmf](https://discuss.jsonapi.org/u/claudenirmf)
#### Post date: [October 21, 2020, 8:23pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/4 "2020-10-21T20:23:01Z")
You must refer to the definition of [“link”](https://jsonapi.org/format/#document-links):
> Links
> Where specified, a `links` member can be used to represent links. The value of each `links` member **MUST** be an object (a “links object”).
> Each member of a links object is a “link”. A link **MUST** be represented as either:
>
> - a string containing the link’s URL.
> - an object (“link object”) which can contain the following members:
> - `href` : a string containing the link’s URL.
> - `meta` : a meta object containing non-standard meta-information about the link.
But I admit that the sentence _“which can contain the following members”_ is not as clear as I would like. So I would (personally) trust the schema and say that “otherLinks” is valid.
Still, avoid making choices that are too edgy unless you are certain of your requirements. They may very well be bad design decisions.
Btw, I have not tested it myself. I am trusting you when you said that the schema allows it.
---
### Author:  [@fdrake](https://discuss.jsonapi.org/u/fdrake)
#### Post date: [October 21, 2020, 8:36pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/5 "2020-10-21T20:36:02Z")
Based on the text of the specification, “otherLinks”, “3”, and “4” are all invalid.
---
### Author:  [@claudenirmf](https://discuss.jsonapi.org/u/claudenirmf)
#### Post date: [October 21, 2020, 9:49pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/6 "2020-10-21T21:49:03Z")
Thanks, @fdrake. I’ll try to test the schema later and submit an issue in case these need to be prevented.
---
### Author:  [@bokara](https://discuss.jsonapi.org/u/bokara)
#### Post date: [October 21, 2020, 10:53pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/7 "2020-10-21T22:53:42Z")
this was my understanding,
- the “3”, “4” examples could be VALID “links”, but not necessarily valid “pagination” (because according to spec, the ‘prev’ etc keys are **MUST**?)
- the “otherLinks” object (with the “3” “4” properties) is INVALID link object because link object **requires “href”** property, according to the [jsonapi schema](http://jsonapi.org/schema), so the “otherLinks” object is **INVALID** both as pagination and/or just as a link?
```auto
"link": {
"description": "A link **MUST** be represented as either: a string containing the link's URL or a link object.",
"oneOf": [
{
"description": "A string containing the link's URL.",
"type": "string",
"format": "uri-reference"
},
{
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"description": "A string containing the link's URL.",
"type": "string",
"format": "uri-reference"
},
"meta": {
"$ref": "#/definitions/meta"
}
}
}
]
},
```
So technically, for the documentation,
> an object (“link object”) which **can contain** the following members:
>
> - `href` : a string containing the link’s URL.
> - `meta` : a meta object containing non-standard meta-information about the link.
the **can contain** is not really true for `href` (it’s a **MUST** for `href`)?
P.S…, the validation test I did in the first post was just from the [jsonapi-validator](https://jsonapi-validator.herokuapp.com/) link in the JSONAPI Implementations page.
I tried another schema validation site and seemed that this is indeed VALID:
```auto
"links": {
"self": "http://testxxx/2",
"4": "http://testxxx/4",
"prev": {
"href": "http://testxxx/1"
},
"next": "http://testxxx/3"
},
```
And with [issue #887](https://github.com/json-api/json-api/issues/887), it feels like the **pagination** schema is kinda redundant? i.e., it doesn’t really help in enforcing anything? (i.e., the ‘prev’, ‘next’, ‘first’, ‘last’ are kinda just recommended keywords to use for pagination? as “#/definitions/links” would be the real (and only) validating schema for links?)
---
### Author:  [@fdrake](https://discuss.jsonapi.org/u/fdrake)
#### Post date: [October 22, 2020, 3:37pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/9 "2020-10-22T15:37:07Z")
@bokara: I think we’re mis-communicating a bit.
I see your link to the JSON Schema that describes JSON:API responses, but… that’s not the specification. (I can’t even find a link to that schema from the site, though I could just be overlooking something.)
This is the specification I’m referring to:
[https://jsonapi.org/format/1.0/](https://jsonapi.org/format/1.0/)
My understanding is that the specification is canonical, not the schema. Your initial post in this thread indicates you understand that the schema can validate non-conforming documents:
> Validation will not yield false negatives, but **could yield false positives** for the sake of flexibility.
So, my understanding, which took some time to arrive at, is that if something is not specifically allowed in the specification, if is not allowed. What follows is that the **links** object CAN contain the following names:
- **self**
- **related** (when the links object is part of a relationship)
- **first**
- **next**
- **last**
- **prev**
**self** and **related** cannot be **null** ; the pagination links can be. The pagination links can only be present for the primary data when it’s a collection, or for a to-many relationship.
JSON:API 1.1 changes things a bit, but that’s not final yet.
-Fred
---
### Author:  [@bokara](https://discuss.jsonapi.org/u/bokara)
#### Post date: [October 22, 2020, 4:04pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/10 "2020-10-22T16:04:55Z")
@fdrake,
thank you for the clarification! yeah, I think we (me) mixed up the spec and schema a bit, sorry about that.
regarding
> I can’t even find a link to that schema from the site…
It’s from the site’s [FQA page](https://jsonapi.org/faq/#is-there-a-json-schema-describing-json-api)
> **self** and **related** cannot be **null** ; the pagination links can be.
That might be the intent of the spec, but seems not feasible technically. i.e., pagination links cannot be null; according to issues [#887](https://github.com/json-api/json-api/issues/887) / [#1512](https://github.com/json-api/json-api/issues/1512)
> What follows is that the **links** object CAN contain the following names:
>
> - **self**
> - **related** (when the links object is part of a relationship)
> - **first**
> - **next**
> - **last**
> - **prev**
That’s actually what I tried to find out / confirm with this post originally… i.e., “ **CAN** contain the following names”, so is it just “CAN contain”, or “CAN **ONLY** contain”? i.e.,
1. other than those 6 names, CAN the **links** object contain other names?
2. If the pagination links can **NOT** be null technically, then can some of the names be missing? e.g., if didn’t want to provide the `last` link, can it be missing? (currently the spec said `prev`, `next`, `first`, `last` “ **MUST** be used for pagination links”)
---
### Author:  [@fdrake](https://discuss.jsonapi.org/u/fdrake)
#### Post date: [October 22, 2020, 4:56pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/11 "2020-10-22T16:56:14Z")
The [**Pagination** section](https://jsonapi.org/format/1.0/#fetching-pagination) says the pagination links can be `null`:
> Keys **MUST** either be omitted or have a `null` value to indicate that a particular link is unavailable.
The [**Links** section](https://jsonapi.org/format/1.0/#document-links) says a link must be represented as a string or a “link object”. That’s the “contradiction” referenced in [issue #1512](https://github.com/json-api/json-api/issues/1512).
I’m interpreting this as:
- the pagination keys may be present in the links object, but
- if they are `null`, they aren’t actually links.
It’s not as clean as it should be (hence, the continuing confusion and those open issues), but that’s how things are in the 1.0 specification. (I don’t actually see anything in the specification that says a link object MUST contain an **href** property, which seems unfortunate.)
I don’t know what you mean about it not being technically feasible; perhaps you’re thinking about the JSON Schema specification, which isn’t canonical?
---
### Author:  [@bokara](https://discuss.jsonapi.org/u/bokara)
#### Post date: [October 22, 2020, 5:11pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/12 "2020-10-22T17:11:02Z")
@fdrake,
thank you for pointing out the “… either be omitted or have a `null` value”, missed the “be omitted” part.
> I don’t know what you mean about it not being technically feasible…
I was referring to currently if a pagination link is null (or any link for that matter), the (schema) validation will **FAIL**. the problem was captured in [issue #887](https://github.com/json-api/json-api/issues/887). i.e., the schema is not capable of distinguishing if it’s a pagination link and nullable…
so I guess if a pagination link is null, then just omit it?
---
### Author:  [@fdrake](https://discuss.jsonapi.org/u/fdrake)
#### Post date: [October 22, 2020, 5:29pm UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/13 "2020-10-22T17:29:06Z")
Or use a better schema.
Omitting the property completely instead of including `null` has the advantage of being easy and compliant with a schema the client (or your tests) might already be using.
Using a better schema has the advantage that a better schema becomes available.
-Fred
---
### Author:  [@jameosil](https://discuss.jsonapi.org/u/jameosil)
#### Post date: [December 19, 2020, 6:24am UTC](https://discuss.jsonapi.org/t/pagination-and-error-source-spec-compliance/2077/14 "2020-12-19T06:24:46Z")
Good information thanks for sharing
[vmware](https://www.fieldengineer.com/skills/vmware-engineer)