8000 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 5 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`
18 changes: 11 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,18 @@ 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
[/schema](http://jsonapi.org/schema). (An update for version 1.1 is
[under development](https://github.com/json-api/json-api/issues/1672).) 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.

[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)
3 changes: 1 addition & 2 deletions _schemas/1.0/schema.json → schemas/1.0/schema.json
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",
"$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": [
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 @@ -24,7 +24,7 @@ const getArgValue = function (name, defaultValue) {
};

// Define root dir
const rootDir = "./_schemas";
const rootDir = "./schemas";

// Define object that will record the full path of all files tested
const files = {};
Expand Down Expand Up @@ -214,7 +214,7 @@ const runSingleTest = async function (ajv, version, results) {
const baseDir = __dirname.replaceAll(/[\/\\]/g, npath.sep).split(npath.sep);
baseDir.pop();
const filePath = options.requiredFile.replaceAll(/[\/\\]/g, npath.sep).split(npath.sep);
if (filePath[0] === "_schemas") {
if (filePath[0] === "schemas") {
filePath.shift();
}
const fullPath = [...baseDir, ...filePath].join(npath.sep);
Expand Down
Loading
0