Skip to content

index.md

Latest commit

 

History

History
107 lines (78 loc) · 4.77 KB

index.md

File metadata and controls

107 lines (78 loc) · 4.77 KB

JSON:API Extension for OpenAPI

This extension facilitates the use of OpenAPI client generators targeting JSON:API documents.

In JSON:API, a resource object contains the type member, which defines the structure of nested attributes and relationships objects. While OpenAPI supports such constraints using allOf inheritance with a discriminator property for the data member, it provides no way to express that the discriminator recursively applies to nested objects.

This extension addresses that limitation by defining additional discriminator properties to guide code generation tools.

URI

This extension has the URI https://www.jsonapi.net/ext/openapi.

Caution

Early preview versions of this specification also permitted using openapi instead of the URI to work around bugs in client generators. This is no longer supported and is not part of the final version.

Namespace

This extension uses the namespace openapi.

Note

JSON:API extensions can only introduce new document members using a reserved namespace as a prefix.

Document Structure

A document that supports this extension MAY include any of the top-level members allowed by the base specification, including any members defined in the Atomic Operations extension.

Resource Objects

In addition to the members allowed by the base specification, the following member MAY be included in attributes and relationships objects:

  • openapi:discriminator - A string that MUST be identical to the type member in the containing resource object.

Here's how an article (a resource of type "articles") might appear in a document:

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "openapi:discriminator": "articles",
      "title": "Rails is Omakase"
    },
    "relationships": {
      "openapi:discriminator": "articles",
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}

Atomic Operations

In addition to the members allowed by the Atomic Operations extension, the following member MAY be included in elements of an atomic:operations array:

  • openapi:discriminator - A free-format string to facilitate the generation of client code.

For example:

POST /operations HTTP/1.1
Host: example.org
Content-Type: application/vnd.api+json; ext="https://www.jsonapi.net/ext/openapi https://jsonapi.org/ext/atomic"
Accept: application/vnd.api+json; ext="https://www.jsonapi.net/ext/openapi https://jsonapi.org/ext/atomic"

{
  "atomic:operations": [{
    "openapi:discriminator": "add-article",
    "op": "add",
    "data": {
      "type": "articles",
      "attributes": {
        "openapi:discriminator": "articles",
        "title": "JSON API paints my bikeshed!"
      }
    }
  }]
}

Processing

A server MAY ignore the openapi:discriminator member in attributes and relationships objects from incoming requests. A server SHOULD ignore the openapi:discriminator member in elements of an atomic:operations array.

A server MUST include the openapi:discriminator member in attributes and relationships objects in outgoing responses. The member value MUST be the same as the type member value of the containing resource object.

A client MAY include the openapi:discriminator member in attributes and relationships objects in outgoing requests. The member value MUST be the same as the type member value of the containing resource object.

A client MAY include the openapi:discriminator member in elements of an atomic:operations array.

Processing Errors

A server SHOULD validate that the value of the openapi:discriminator member in attributes and relationships objects is identical to the type member in the containing resource object. When validation fails, the server MUST respond with a 409 Conflict and SHOULD include a document with a top-level errors member that contains an error object.