JSON Schema Rendering

Apiary’s interactive documentation is able to render JSON Schema associated with your payloads when it’s defined (or Apiary is able to generate one).

A validation schema can be defined in your API Blueprint using the specific Schema section.

+ Response 201 (application/json)

    + Schema

          {
              "type": "object",
              "required": true,
              "additionalProperties": false,
              "properties": {
                "ssn": {
                  "type": "string",
                  "required": false,
                  "description": "Customer Social Security Number"
                },
                "first_name": {
                  "type": "string",
                  "required": true,
                  "description": "Customer Name"
                },
                "surname": {
                  "type": "string",
                  "required": true,
                  "description": "Customer Surname"
                },
                "address1": {
                  "type": "string",
                  "required": true,
                  "description": "Address Line 1"
                }
              }
            }

It is a different matter when you are employing MSON as description language for your data structures. In that case, Apiary is able to automatically generate a JSON Schema, and you do not have to write any code for it. The same things we’ve seen above are still valid.

MSON Example

The following data structure:

# Company

- name: Apiary
- founder (string)
- founded: 2011 (number) - The year in which the company was founded
- address
    - street: 235 Ninth Street
    - city: San Francisco
    - state: California

will result in the following JSON Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "founder": {
      "type": "string"
    },
    "founded": {
      "type": "number",
      "description": "The year in which the company was founded"
    },
    "address": {
      "type": "object",
      "properties": {
        "street": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        }
      }
    }
  },
  "$schema": "https://json-schema.org/draft-04/schema#"
}

Whenever Apiary is able to detect a Schema no matter if generated or provided from the user, it will be rendered into your documentation, into the Machine Column section, right near the Body.

JSON Schema Button

As you can see, the Schema is collapsed by default. You can expand it clicking the “Show JSON Schema” button.

Note

If your request or response includes MSON or JSON Schema but does not provide a body, it will be expanded by default.

Related topics