# json-api/schema-validation

Source: https://apigenie.pl/docs/linter/openapi/rules/json-api-schema-validation

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. In the rulesets: JsonApi at error.

This rule checks that the schemas of the JSON:API request bodies and responses describe JSON:API
documents: a top-level object with `data`, `errors` or `meta`, and resource objects with `type`
and `id`.

## Rule details

A JSON:API document has a fixed shape, and a schema that departs from it (a bare array, a string)
produces clients that cannot be JSON:API clients.

The rule reads the schema of every `application/vnd.api+json` request body and response, with
references followed and the parts of an `allOf` taken together, and reports:

- `JSON:API document schema is not an object` when its `type` does not allow an object;
- `JSON:API document schema declares none of data, errors and meta`, when it declares properties;
- `JSON:API document schema declares member '...', which is not a top-level member of JSON:API`
  for a property other than `data`, `errors`, `meta`, `jsonapi`, `links` and `included`;
- `JSON:API document schema requires both data and errors`;
- `JSON:API errors member is not an array`;
- `JSON:API resource object schema does not declare type` and, in responses and in `included`,
  `... does not declare id`, for each resource object of `data` and `included` (the schema of the
  member, the items of an array, the branches of `anyOf` and `oneOf`) that declares properties;
- `JSON:API resource object schema declares member '...' outside attributes and relationships`
  for a property other than `type`, `id`, `lid`, `attributes`, `relationships`, `links` and
  `meta`.

A property with a colon, the namespaced member of a JSON:API extension, is accepted everywhere. A
schema without properties, such as a bare `type: object`, describes no members and passes. A
schema shared by several operations is reported once. The rule is part of the `json-api` ruleset.

## Examples

**Good**. The smallest document schema JSON:API allows.

```yaml
paths:
  /users/current:
    get:
      responses:
        "200":
          description: The current user.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                  data:
                    type: object
```

**Bad**. A string is not a JSON:API document.

```yaml
paths:
  /users/current:
    get:
      responses:
        "200":
          description: The current user.
          content:
            application/vnd.api+json:
              schema:
                type: string
```
