Convert JSON to JSON Schema draft 4 compatible with Swagger 2.0

Question

I've been given some JSON files generated by a REST API with plenty of properties.

I've created a Swagger 2.0 definition for this API and need to give it the corresponding schema for the response.

The main problem: this JSON file has loads of properties. It would take so much time and I would make many mistakes if I write the schema manually. And it’s not the only API I need to describe.

I know there are some tools to convert JSON to JSON schemas but, if I’m not mistaken, Swagger only has $refs to other objects definitions thus only has one level whereas the tools I’ve found only produce tree structured schemas. My question: is there any tool to convert a JSON (or JSON Schema) to a Swagger 2.0 compatible one ?

Note: I'm working in YAML but I wouldn't be an issue, would it ?

For example, what I need:

  List of Movements:
    type: "array"
    items:
      $ref: "#/definitions/Movement"
  Movement:
    properties:
      dateKey:
        type: "string"
      movement:
        $ref: "#/definitions/Stock"
    additionalProperties: false
  Stock:
    properties:
      stkUnitQty:
        type: "string"
      stkDateTime:
        type: "string"
      stkUnitType:
        type: "string"
      stkOpKey:
        type: "string"
    additionalProperties: false

For my JSON document:

[
  {
    "dateKey": "20161110",
    "stkLvls": [
      {
        "stkOpKey": "0",
        "stkUnitType": "U",
        "stkDateTime": "20161110T235010.240+0100",
        "stkUnitQty": 30
      }
    ]
  },
  {
    "dateKey": "20161111",
    "stkLvls": [
      {
        "stkOpKey": "0",
        "stkUnitType": "U",
        "stkDateTime": "20161111T231245.087+0100",
        "stkUnitQty": 21
      }
    ]
  }
  ]

But, what http://jsonschema.net/#/ gives me:

---
"$schema": http://json-schema.org/draft-04/schema#
type: array
items:
  type: object
  properties:
    dateKey:
      type: string
    stkLvls:
      type: array
      items:
        type: object
        properties:
          stkOpKey:
            type: string
          stkUnitType:
            type: string
          stkDateTime:
            type: string
          stkUnitQty:
            type: integer
        required:
        - stkOpKey
        - stkUnitType
        - stkDateTime
        - stkUnitQty
  required:
  - dateKey
  - stkLvls

I'm new to that, but curious, don't hesitate to explain deeply.

Thank you in advance for your help !

Answer 1

I also needed a converter tool and came across this. So far it seems to work pretty well. It does both JSON and YAML formats.

https://swagger-toolbox.firebaseapp.com/

Given this JSON (their sample):

{
  "id": 1,
  "name": "A green door",
  "price": 12,
  "testBool": false,
  "tags": [
    "home",
    "green"
  ]
}

it generated this:

{
    "required": [
        "id",
        "name",
        "price",
        "testBool",
        "tags"
    ],
    "properties": {
        "id": {
            "type": "number"
        },
        "name": {
            "type": "string"
        },
        "price": {
            "type": "number"
        },
        "testBool": {
            "type": "boolean"
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    }
}

Answer 2

I know there are some tools to convert JSON to JSON schemas but, if I’m not mistaken, Swagger only has $refs to other objects definitions thus only has one level

You are mistaken. Swagger will respect any valid v4 JSON schema, as long as it only uses the supported subset.

The Schema Object...is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.

It goes on to list the parts of JSON schema which are supported, and the bits which are not, and the bits which are extended by swagger.