10000 Make schema public and restore `/schema` by bradjones1 · Pull Request #1750 · json-api/json-api · GitHub
[go: up one dir, main page]

Skip to content

Make schema public and restore /schema #1750

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: gh-pages
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,5 @@ Gemfile.lock
# Ignore the node_modules directory

/node_modules

/yarn.lock
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ npm install
Then you can run the schema validator by running one of the following commands :

`
node ./_schemas/scripts/validator.js
node ./schemas/scripts/validator.js
`

or
Expand All @@ -40,5 +40,5 @@ npm run test-schema
This script validates all test files against all available versions of the specification.
Some options can be used :
- `--verbose` : allows more verbose output.
- `-f relative-path` : the relative path of the only file to test. For example : `npm run test-schema -- -f _schemas/1.0/response/valid/with_success/complete.json`
- `-f relative-path` : the relative path of the only file to test. For example : `npm run test-schema -- -f schemas/1.0/response/valid/with_success/complete.json`
- `-v version` : the version of the specification to use to test the files. For example : `npm run test-schema -- -v 1.0`
15 changes: 8 additions & 7 deletions faq/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ show_sidebar: true

## <a href="#what-is-the-meaning-of-json-apis-version" id="what-is-the-meaning-of-json-apis-version" class="headerlink"></a> What is the meaning of JSON:API's version?

Now that JSON:API has reached a stable version 1.0, it will always be
Following JSON:API's first stable version (1.0), it will always be
backwards compatible using a _never remove, only add_ strategy.

A version is maintained in order to:
Expand Down Expand Up @@ -81,14 +81,15 @@ don’t can be easily [worked around](/recommendations/#patchless-clients).

## <a href="#is-there-a-json-schema-describing-json-api" id="is-there-a-json-schema-describing-json-api" class="headerlink"></a> Is there a JSON Schema describing JSON:API?

Yes, you can find the JSON Schema definition at
[http://jsonapi.org/schema](http://jsonapi.org/schema). This 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.
Yes, you can find the response JSON Schema definition for version 1.0 at
[`https://jsonapi.org/schema`](http://jsonapi.org/schema). (An update for

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing an "s"?

version 1.1 is [under development](https://github.com/json-api/json-api/issues/1672).)

[Additional schemas](/schemas/1.0/) are provided for requests creating and
updating resources or updating relationships.

You can find more information about the JSON Schema format at
[http://json-schema.org](http://json-schema.org).
[https://json-schema.org](https://json-schema.org).

## <a href="#resource-collections-returned-as-arrays" id="resource-collections-returned-as-arrays" class="headerlink"></a> Why are resource collections returned as arrays instead of sets keyed by ID?

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,6 @@
"readdirp": "^3.6.0"
},
"scripts": {
"test-schema": "node -i _schemas/scripts/validator.js"
"test-schema": "node -i schemas/scripts/validator.js"
}
}
5 changes: 5 additions & 0 deletions schema
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"$id": "https://jsonapi.org/schema",
"$comment": "JSON:API JSON Schema. This well-known schema URI references versioned JSON Schemas. JSON:API versions are always backwards-compatible.",
"$ref": "https://jsonapi.org/schemas/1.0/schema.json"
}
10 changes: 10 additions & 0 deletions schemas/1.0/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
layout: page
title: JSON Schemas for specification version 1.0
show_sidebar: false
---

* [Response schema](./schema.json)
* [Create Resource (`POST`)](./schema_create_resource.json)
* [Update Resource (`PATCH`)](./schema_create_resource.json)
* [Update Relationship (`PATCH`)](./schema_update_relationship.json)
101 changes: 75 additions & 26 deletions _schemas/1.0/schema.json → schemas/1.0/schema.json
Original file line number Diff line number Diff line change
@@ -1,15 +1,11 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://jsonapi.org/schemas/spec/v1.0/draft",
"$comment": "The $id URI should be modified before releasing. This URI does not need to be network addressable. It is an ID only.",
"$id": "https://jsonapi.org/schemas/1.0/schema.json",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

   "$id": "https://jsonapi.org/schemas/spec/v1.0/draft",
   "$comment": "The $id URI should be modified before releasing. This URI does not need to be network addressable. It is an ID only.",

The schema should remain a draft until it has been publicly reviewed.

"title": "JSON:API Schema",
"description": "This schema only validates RESPONSES from a request. Validating request payloads requires slightly different constraints.",
"allOf": [
{
"$ref": "#/definitions/requiredTopLevelMembers"
},
{
"$ref": "#/definitions/oneOfDataOrErrors"
}
],
"type": "object",
Expand All @@ -34,8 +30,13 @@
"$ref": "#/definitions/meta"
}
},
"dependencies": {
"included": ["data"]
"dependentSchemas": {
"included": {
"$ref": "#/definitions/includedOnlyIfContainsData"
},
"data": {
"$ref": "#/definitions/oneOfDataOrErrors"
}
},
"additionalProperties": false,
"definitions": {
Expand All @@ -49,21 +50,16 @@
"": true
},
"not": {
"$comment": "This is what the specification requires, but it seems bad. https://github.com/json-api/json-api/issues/1553",
"anyOf": [
{
"required": [
"type"
]
},
"$comment": "This is what the specification requires, but is removed in v1.1. https://github.com/json-api/json-api/issues/1553",
"not": {
"$ref": "#/definitions/relationshipsForbiddenMemberName"
},
"allOf": [
{
"required": [
"id"
]
"additionalProperties": true
}
]
},
"additionalProperties": false
}
},
"data": {
"description": "The document's \"primary data\" is a representation of the resource or collection of resources targeted by a request.",
Expand Down Expand Up @@ -236,16 +232,31 @@
"additionalProperties": false
},
"oneOfDataOrErrors": {
"not": {
"type": "object",
"properties": {
"errors": true
},
"required": [
"errors"
]
}
},
"includedOnlyIfContainsData": {
"type": "object",
"dependencies": {
"additionalProperties": true,
"properties": {
"data": {
"not": {
"required": [
"errors"
]
}
"$ref": "#/definitions/data"
},
"included": {
"$ref": "#/definitions/included"
}
}
},
"required": [
"data",
"included"
]
},
"pagination": {
"type": "object",
Expand Down Expand Up @@ -311,12 +322,27 @@
},
"anyOf": [
{
"properties": {
"data": {
"$ref": "#/definitions/linkage"
}
},
"required": ["data"]
},
{
"properties": {
"meta": {
"$ref": "#/definitions/meta"
}
},
"required": ["meta"]
},
{
"properties": {
"links": {
"$ref": "#/definitions/relationshipLinks"
}
},
"required": ["links"]
}
],
Expand Down Expand Up @@ -423,11 +449,19 @@
"anyOf": [
{
"type": "object",
"additionalProperties": true,
"properties": {
"type": true
},
"required": [
"type"
]
},
{
"additionalProperties": true,
"properties": {
"id": true
},
"type": "object",
"required": [
"id"
Expand All @@ -440,18 +474,33 @@
"anyOf": [
{
"type": "object",
"properties": {
"meta": {
"$ref": "#/definitions/meta"
}
},
"required": [
"meta"
]
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/data"
}
},
"required": [
"data"
]
},
{
"type": "object",
"properties": {
"errors": {
"$ref": "#/definitions/errors"
}
},
"required": [
"errors"
]
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://jsonapi.org/schemas/spec/v1.0/draft/create/resource",
"$comment": "The $id URI should be modified before releasing. This URI does not need to be network addressable. It is an ID only.",
"$id": "https://jsonapi.org/schemas/1.0/schema_create_resource.json",
"title": "JSON:API Schema for POST request",
"description": "This schema only validates a request for POSTing a new resource.",
"type": "object",
Expand All @@ -13,10 +12,10 @@
"$ref": "#/definitions/resource"
},
"jsonapi": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/jsonapi"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/jsonapi"
},
"meta": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/meta"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/meta"
}
},
"additionalProperties": false,
Expand All @@ -27,20 +26,20 @@
"type": "object",
"allOf": [
{
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/resourceIdentificationNew"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/resourceIdentificationNew"
}
],
"properties": {
"id": true,
"type": true,
"attributes": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/attributes"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/attributes"
},
"meta": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/meta"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/meta"
},
"relationships": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/relationshipsFromRequest"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/relationshipsFromRequest"
}
},
"additionalProperties": false
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://jsonapi.org/schemas/spec/v1.0/draft/update/relationship",
"$comment": "The $id URI should be modified before releasing. This URI does not need to be network addressable. It is an ID only.",
"$id": "https://jsonapi.org/schemas/1.0/schema_update_relationship.json",
"title": "JSON:API Schema for POST request",
"description": "This schema only validates a request for PATCHing a resource's relationship.",
"type": "object",
Expand All @@ -10,13 +9,13 @@
],
"properties": {
"data": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/linkage"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/linkage"
},
"jsonapi": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/jsonapi"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/jsonapi"
},
"meta": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/meta"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/meta"
}
},
"additionalProperties": false
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://jsonapi.org/schemas/spec/v1.0/draft/update/resource",
"$comment": "The $id URI should be modified before releasing. This URI does not need to be network addressable. It is an ID only.",
"$id": "https://jsonapi.org/schemas/1.0/schema_update_resource.json",
"title": "JSON:API Schema for POST request",
"description": "This schema only validates a request for PATCHing a resource.",
"type": "object",
Expand All @@ -13,10 +12,10 @@
"$ref": "#/definitions/resource"
},
"jsonapi": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/jsonapi"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/jsonapi"
},
"meta": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/meta"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/meta"
}
},
"additionalProperties": false,
Expand All @@ -27,20 +26,20 @@
"type": "object",
"allOf": [
{
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/resourceIdentification"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/resourceIdentification"
}
],
"properties": {
"id": true,
"type": true,
"attributes": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/attributes"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/attributes"
},
"meta": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/meta"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/meta"
},
"relationships": {
"$ref": "https://jsonapi.org/schemas/spec/v1.0/draft#/definitions/relationshipsFromRequest"
"$ref": "https://jsonapi.org/schemas/1.0/schema.json#/definitions/relationshipsFromRequest"
}
},
"additionalProperties": false
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"type": "article",
"id": "1",
"attributes": {
"somthing": "to know"
"something": "to know"
}
}
],
Expand Down
Loading
Loading
0