Skip to content

Commit

Permalink
added JSON schemas 🔍
Browse files Browse the repository at this point in the history 
please see / should fix
json-api#867
json-api#851

partially fixes
json-api#406
---> see my following answer in
json-api#867 regarding versioning
  • Loading branch information
redaktor committed Sep 14, 2015
1 parent 9bd3683 commit 6b7c465
Show file tree
Hide file tree
Showing 3 changed files with 523 additions and 0 deletions.
71 changes: 71 additions & 0 deletions schemas/1_1/create.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://jsonapi.org/schemas/create.json",

This comment has been minimized.

Sign in to view

Copy link
@eneuhauser

eneuhauser Sep 24, 2015

The ID should be "http://jsonapi.org/schemas/1_1/create.json". That would need to be changed in each of the schemas.

This comment has been minimized.

Sign in to view

Copy link
@sebilasse

sebilasse Sep 28, 2015

foreword: thanks for the quick reply. I ran into kind of "hardware disaster" (managed to crash 2 MBP on 1 journey) - so: I am sorry to be so "lazy" - should be solved by tomorrow ...
-->
Yes, right. I was not sure about "versioning" at all and of your favorite "versioning syntax" for the folder name.
Is 1_1 ok? Or 1.1? Or 1_1_0 or so?
"title": "JSON API Schema",
"description": "This is a schema for creating (e.g. via POST) in the JSON API format. For more, see http://jsonapi.org",
"allOf": [
{
"$ref": "#/definitions/create"
}
],

"definitions": {
"create": {
"allOf": [
{
"$ref": "http://jsonapi.org/schemas/request.json#/definitions/request"

This comment has been minimized.

Sign in to view

Copy link
@eneuhauser

eneuhauser Sep 24, 2015

Based on the Space Telescope Science Institute schema guide, you could change the $ref to:

"$ref": "request.json#/definitions/request"

The advantage here is that you won't have to update each reference when creating new versions.

This comment has been minimized.

Sign in to view

Copy link
@sebilasse

sebilasse Sep 28, 2015

Yes right. Forgot about it.
btw: The schemas derived from a TS interface to JSON schema project which I wanted to upgrade to TS 1.6.2 -
note to me: make baseURL relative where I can ;)
},
{
"properties": {
"data": {
"$ref": "#/definitions/data"
}
}
}
]
},
"data": {
"description": "The document's \"primary data\" is a representation of the resource or collection of resources targeted by a request.",
"oneOf": [
{
"$ref": "#/definitions/resource"
},
{
"description": "An array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections.",
"type": "array",
"items": {
"$ref": "#/definitions/resource"
},
"uniqueItems": true
}
]
},
"resource": {
"description": "\"Resource objects\" appear in a JSON API document to represent resources. Ids are required, except on the creation request.",
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
},
"attributes": {
"$ref": "http://jsonapi.org/schemas/request.json#/definitions/attributes"
},
"relationships": {
"$ref": "http://jsonapi.org/schemas/request.json#/definitions/relationships"
},
"links": {
"$ref": "http://jsonapi.org/schemas/request.json#/definitions/links"
},
"meta": {
"$ref": "http://jsonapi.org/schemas/response.json#/definitions/meta"
}
}
}
}
}
204 changes: 204 additions & 0 deletions schemas/1_1/request.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://jsonapi.org/schemas/request.json",
"title": "JSON API Schema",
"description": "This is the base schema for the JSON API format. For more, see http://jsonapi.org",
"allOf": [
{
"$ref": "#/definitions/request"
}
],

"definitions": {
"request": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"$ref": "#/definitions/data"
},
"included": {
"description": "To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources along with the requested primary resources. Such responses are called \"compound documents\".",
"type": "array",
"items": {
"$ref": "#/definitions/resource"
},
"uniqueItems": true
},
"meta": {
"$ref": "http://jsonapi.org/schemas/response.json#/definitions/meta"

This comment has been minimized.

Sign in to view

Copy link
@eneuhauser

eneuhauser Sep 24, 2015

This creates a cyclical dependency between request.json and response.json. You noted that this is the "base schema", so meta should be defined here and referenced in response.json.
},
"links": {
"description": "Link members related to the primary data.",
"allOf": [
{
"$ref": "#/definitions/links"
},
{
"$ref": "http://jsonapi.org/schemas/response.json#/definitions/pagination"
}
]
},
"jsonapi": {
"$ref": "http://jsonapi.org/schemas/response.json#/definitions/jsonapi"
}
}
},

"data": {
"description": "The document's \"primary data\" is a representation of the resource or collection of resources targeted by a request.",
"oneOf": [
{
"$ref": "#/definitions/resource"
},
{
"description": "An array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections.",
"type": "array",
"items": {
"$ref": "#/definitions/resource"
},
"uniqueItems": true
}
]
},
"resource": {
"allOf": [
{
"$ref": "http://jsonapi.org/schemas/create.json#/definitions/resource"
},
{
"required": [
"id"
]
}
]
},
"links": {
"description": "A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.",
"type": "object",
"properties": {
"self": {
"description": "A `self` member, whose value is a URL for the relationship itself (a \"relationship URL\"). This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an `author` from an `article` without deleting the people resource itself.",
"type": "string",
"format": "uri"
},
"related": {
"$ref": "#/definitions/link"
}
},
"additionalProperties": true
},
"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"
},
{
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"description": "A string containing the link's URL.",
"type": "string",
"format": "uri"
},
"meta": {
"$ref": "http://jsonapi.org/schemas/response.json#/definitions/meta"
}
}
}
]
},

"attributes": {
"description": "Members of the attributes object (\"attributes\") represent information about the resource object in which it's defined.",
"type": "object",
"patternProperties": {
"^(?!relationships$|links$)\\w[-\\w_]*$": {
"description": "Attributes may contain any valid JSON value."
}
},
"additionalProperties": false
},

"relationships": {
"description": "Members of the relationships object (\"relationships\") represent references from the resource object in which it's defined to other resource objects.",
"type": "object",
"patternProperties": {
"^\\w[-\\w_]*$": {
"properties": {
"links": {
"$ref": "#/definitions/links"
},
"data": {
"description": "Member, whose value represents \"resource linkage\".",
"oneOf": [
{
"$ref": "#/definitions/relationshipToOne"
},
{
"$ref": "#/definitions/relationshipToMany"
}
]
},
"meta": {
"$ref": "http://jsonapi.org/schemas/response.json#/definitions/meta"
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"relationshipToOne": {
"description": "References to other resource objects in a to-one (\"relationship\"). Relationships can be specified by including a member in a resource's links object.",
"anyOf": [
{
"$ref": "#/definitions/empty"
},
{
"$ref": "#/definitions/linkage"
}
]
},
"relationshipToMany": {
"description": "An array of objects each containing \"type\" and \"id\" members for to-many relationships.",
"type": "array",
"items": {
"$ref": "#/definitions/linkage"
},
"uniqueItems": true
},
"empty": {
"description": "Describes an empty to-one relationship.",
"type": "null"
},
"linkage": {
"description": "The \"type\" and \"id\" to non-empty members.",
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
},
"meta": {
"$ref": "http://jsonapi.org/schemas/response.json#/definitions/meta"
}
},
"additionalProperties": true
}
}
}
Loading

0 comments on commit 6b7c465

Please sign in to comment.