Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
OpenAPI 3.0 schemas that comply with the JSON:API 1.0 specification
JSONAPIObject:
description: Includes the current JSON:API version for this specification as well as optional meta information
type: object
required:
- version
properties:
version:
type: string
default: '1.0'
example: '1.0'
meta:
type: object
JSONAPIResourceIdentifierObject:
title: JSON:API Resource Identifier Object
description: |
A JSON:API-compliant resource identifier object. An inheritable object schema that contains the basic framework of a Resource Identifier Object from the JSON:API spec.
A “resource identifier object” is an object that identifies an individual resource.
A “resource identifier object” MUST contain `type` and `id` members.
A “resource identifier object” MAY also include a `meta` member, whose value is a meta object that contains non-standard meta-information. If necessary, the `meta` property should be added by the inheriting schema.
type: object
required:
- type
- id
properties:
type:
$ref: '#/components/schemas/JSONAPIType'
id:
$ref: '#/components/schemas/JSONAPIId'
JSONAPIResourceObject:
title: JSON:API Resource Object
description: |
A JSON:API-compliant resource object. An inheritable object schema that contains the basic framework of a Resource Object from the JSON:API spec.
The `attributes`, `relationship`, and `meta` properties are added, as necessary, by the inheriting schema.
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/JSONAPIType'
id:
$ref: '#/components/schemas/JSONAPIId'
links:
$ref: '#/components/schemas/JSONAPILinksObject'
JSONAPIType:
title: JSON:API type Member
description: |
The `type` member is used to describe resource objects that share common attributes and relationships.
Note: The type member is required in every resource object throughout requests and responses in JSON:API. There are some cases, such as when POSTing to an endpoint representing heterogeneous data, when the type could not be inferred from the endpoint. However, picking and choosing when it is required would be confusing; it would be hard to remember when it was required and when it was not. Therefore, to improve consistency and minimize confusion, type is always required.
type: string
JSONAPIId:
title: JSON:API id Member
description: Every resource object MUST contain an id member and a type member (exception-the id member is not required when the resource object originates at the client and represents a new resource to be created on the server). Within a given API, each resource object’s type and id pair MUST identify a single, unique resource.
type: string
JSONAPILinksObject:
title: JSON:API Links Object
description: May contain `self`, `related`, or pagination links (first, last, prev, next).
properties:
self:
$ref: '#/components/schemas/JSONAPILink'
related:
$ref: '#/components/schemas/JSONAPILink'
first:
$ref: '#/components/schemas/JSONAPILink'
last:
$ref: '#/components/schemas/JSONAPILink'
prev:
$ref: '#/components/schemas/JSONAPILink'
next:
$ref: '#/components/schemas/JSONAPILink'
JSONAPILink:
title: JSON:API Link
description: A JSON:API link can be either a URL string or a structured link object.
oneOf:
- $ref: '#/components/schemas/URL'
- $ref: '#/components/schemas/JSONAPILinkObject'
URL:
type: string
format: url
example: 'https://example.com/'
JSONAPILinkObject:
title: JSON:API Link Object
description: a structured representation of a URL
type: object
required:
- href
properties:
href:
type: string
example: 'https://example.com/'
meta:
type: object
example:
count: '10'
JSONAPIRelationshipObject:
title: JSON:API Relationship Object
description: |
This schema can be used when defining `relationships` objects within a JSON:API resource object.
The value of the relationships key MUST be an object (a “relationships object”). Members of the relationships object (“relationships”) represent references from the resource object in which it’s defined to other resource objects.
Relationships may be to-one or to-many.
type: object
oneOf:
- type: object
description: links object
properties:
links:
$ref: '#/components/schemas/JSONAPILinksObject'
- type: object
description: |
Resource linkage in a compound document allows a client to link together all of the included resource objects without having to GET any URLs via links.
Resource linkage MUST be represented as one of the following:
* null for empty to-one relationships.
* an empty array ([]) for empty to-many relationships.
* a single resource identifier object for non-empty to-one relationships.
* an array of resource identifier objects for non-empty to-many relationships.
properties:
data:
oneOf:
- type: string
description: null indicates an empty to-one relationship
default: 'null'
- type: array
description: an empty array indicates an empty to-many relationship; an array with objects indicates a non-empty to-many relationship
items:
$ref: '#/components/schemas/JSONAPIResourceIdentifierObject'
- $ref: '#/components/schemas/JSONAPIResourceIdentifierObject'
- type: object
description: a meta object that contains non-standard meta-information about the relationship
properties:
meta:
type: object
JSONAPIErrorResponse:
title: JSON:API Error Response
description: A JSON:API-compliant error response. This object is inherited by the specific response type.
type: object
required:
- errors
properties:
errors:
description: An array of Error objects
type: array
minItems: 1
items:
description: A JSON:API-compliant error object. According to the JSON:API, none of the properties are required. For our purposes, we have made status and title required.
type: object
required:
- status
- title
properties:
id:
description: a unique identifier for this particular occurrence of the problem
type: string
format: uuid
links:
description: a link to further details about this particular occurrence of the problem
type: object
properties:
about:
$ref: '#/components/schemas/JSONAPILink'
status:
description: the HTTP status code applicable to this problem
type: string
minLength: 3
maxLength: 3
code:
description: an application-specific error code
type: string
title:
description: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization
type: string
detail:
description: a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized
type: string
source:
description: contains references to the source of the error
type: object
properties:
pointer:
description: a JSON Pointer [RFC6901] to the associated entity in the request document
type: string
parameter:
description: indicates which URI query parameter caused the error
type: string
meta:
description: a JSON meta object with non-standard meta-information about the error
type: object
additionalProperties: true
@omarryhan

This comment has been minimized.

Copy link

@omarryhan omarryhan commented Sep 16, 2020

Thanks for sharing!

I found this set of schemas while Googling around, and I think it's similar to yours in terms of what it's trying to accomplish. I'm curious to hear from you, how does it compare to yours?

@JoeAlamo

This comment has been minimized.

Copy link

@JoeAlamo JoeAlamo commented Sep 22, 2020

I would also like to know that. @omarryhan , did you experiment with either of them?

@omarryhan

This comment has been minimized.

Copy link

@omarryhan omarryhan commented Sep 22, 2020

Nah, I gave up on trying to make JSON:API work with OpenAPI. AFAIR, the one at columbia.edu is more extensive, didn't compare them thoroughly though. Hope that helps @JoeAlamo

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.