Skip to content

Instantly share code, notes, and snippets.

@maxnasonov
Forked from naesean/jsonapi_oas.yml
Created May 3, 2023 17:01
Show Gist options
  • Save maxnasonov/1bc5537fd05efebc4de6a372b69e7cc8 to your computer and use it in GitHub Desktop.
Save maxnasonov/1bc5537fd05efebc4de6a372b69e7cc8 to your computer and use it in GitHub Desktop.
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment