Unable to use JSON Schema with "definitions"

[chrisnappin]

When using a JSON Schema with "definitions" blocks, speccy returns the error Schema object cannot have additionalProperty: definitions.

For example, consider an OpenAPI v3.0.2 definition in yaml format with the following reference to a JSON schema:

...
components:
  schemas:
    Journal:
      $ref: 'mes-journal-schema/simple-schema.json'
...

Then a really simple JSON schema as follows:

{
  "id": "https://example.com/arrays.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Journal",
  "type": "object",
  "additionalProperties": false,
  "description": "Simple JSON Schema",
  "properties": {
    "message": {
      "$ref": "#/definitions/message"
    }
  },
  "definitions": {
    "message": {
      "type": "string"
    }
  }
}

Then invoking speccy via an npm script within my package.json:

  ...
  "devDependencies": {
    "speccy": "^0.8.7"
  },
  "scripts": {
    "check": "speccy lint -v -s info-contact -j openapi.yaml"
  },
  ...

When running the linter:

$ npm run check

> [email protected] check /Users/chris.nappin/Development/mes/mes-api-definitions
> speccy lint -v -s info-contact -j openapi.yaml

GET openapi.yaml
GET /Users/chris.nappin/Development/mes/mes-api-definitions/mes-journal-schema/simple-schema.json 
Specification schema is invalid.

#/components/schemas/Journal
Schema object cannot have additionalProperty: definitions

Context

I'm attempting to add OpenAPI definitions to en existing project with JSON Schema already used for other purposes (e.g. generating Typescript interface types)

Your environment

• Node Version: v8.10.0
• Operating system and version: MacOS Mojave (v10.14.3)
• Speccy Version: 0.9.0, 0.8.7, 0.8.6, 0.8.5

[MikeRalphson]

This is as designed, from the specification:

Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.

Theoretically, https://github.com/wework/json-schema-to-openapi-schema might be able to rewrite your JSON Schema file (as I see you're using the -j option) in some way, and depending on how you're $refing into it, but I suspect this is out of scope for speccy itself.

[chrisnappin]

Thanks for getting back to me.

Yes, we're trying to use speccy to convert a JSON schema to an Open API schema. I couldn't see any details on limitations in speccy in this area?

We'd like to have our schema files separate to our main openapi.yml (since the schema are used for other purposes) with a single $ref to each schema.

An example of the complex JSON schemas we're using is https://github.com/dvsa/mes-api-definitions/blob/develop/mes-journal-schema/schema-examiner-work-schedule.json. I'm not that familiar with JSON schema but I can't see how we can structure repeating nested objects without putting them under a "definitions" section?

Do you have any advice on how we can use speccy schema conversion with complex schemas?

[Raymond26]

Hey @chrisnappin what approach did you end up taking? I am doing something similar. Need to validate an OpenAPI spec that is in the request body.

[chrisnappin]

We had to abandon any use of open api! This was a complete show stopper for us I'm afraid.

[Raymond26]

Ah darn. Ok, thanks for responding.

[cspotcode]

Speccy should be migrating JSON schema "definitions" into the spec's "components/schemas" object, right?