json-api/content-type

Since 0.0.1 · fixed by --fix

This rule ensures that every request and response in an OpenAPI schema provides the application/vnd.api+json media type.

Rule Details

The json-api/content-type rule is designed to ensure that every request and response in an OpenAPI schema provides the application/vnd.api+json media type. This rule is specifically useful for APIs that adhere to the JSON:API specification.

Configuration

None.

Examples

Good. By marking the response with the correct media type, API authors enable enhancements specific to JSON:API.

openapi: 3.1.0
info: ...
paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/UserListResponse"

Bad. Although the response is a valid JSON:API document, it is not obvious from this definition.

openapi: 3.1.0
info: ...
paths:
  /users:
    get:
      responses:
        "200":
          description: A list of users.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"

When Not to Use It

If the API is not meant to be JSON:API compatible.

Automatic fixes

When invoked with --fix, a sole application/json content entry is renamed to application/vnd.api+json, preserving its full media-type value. Content maps with multiple entries remain manual.

Compatibility

This rule is compatible with all OpenAPI 3.x version.