swagger - Adding schema definition in openapi3.0 yaml using external .yaml file

Question

I've openapi3.0 YAML file which is written according to openapi3.0 format and I am using $ swagger-cli validate simple_violation_bool.yaml and its gave True/False based on whether simple_violation_bool.yaml is valid OpenAPI 3.0 or not.

Below is the content of my OpenAPI3.0 yaml file i.e. simple_violation_bool.yaml and I am trying to add schema definition using $ref: './violation_schema.yaml#/NISE but it giving error during $ swagger-cli validate simple_violation_bool.yaml.

Below is my simple_violation_bool.yaml openapi3.0 YAML file.

simple_violation_bool.yaml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: simple_violation_bool
  license:
    name: MIT
  description: |
    Simple violation in simple_violation_bool module
externalDocs:
  description: NISE simple_violation_bool.
servers:
  - url: https://swagger.io/specification/
paths: {}

components:
  schemas:
    NISE:
      type: object
      title: The Root Schema
      required:
        - description
        - id
        - name
        - ports
      properties:
        description:
          type: string
          title: The Descripton Schema
          schema:
            $ref: './violation_schema.yaml#/NISE'
        id:
          type: integer
          title: The Id Schema
          default: 0
          format: int64
          schema:
            $ref: './violation_schema.yaml#/NISE'
        name:
          type: string
          title: The Name Schema
          schema:
            $ref: './violation_schema.yaml#/NISE'
        ports:
          type: array
          title: The Ports Schema
          schema:
            $ref: './violation_schema.yaml#/NISE'
          items:
            type: integer
            title: The items Schema
            default: 0
            schema:
              $ref: './violation_schema.yaml#/NISE'
        value:
          type: object
          title: The Value Schema
          schema:
            $ref: './violation_schema.yaml#/NISE'

And here is the content of schema definition file violation_schema.yaml which I am trying to add using $ref: './violation_schema.yaml.

violation_schema.yaml

NISE:
  properties:
    description:
      type: string
    id:
      type: integer
    name:
      type: string
    ports:
      type: array
    value:
      type: object

Below is the error log after I run $ swagger-cli validate simple_violation_bool.yaml

Error Log:

Running swagger-cli validate on simple_violation_bool.yaml .....
Swagger schema validation failed. 
  Data does not match any schemas from 'oneOf' at #/components/schemas/NISE
    Data does not match any schemas from 'oneOf' at #/components/schemas/NISE/properties/value
      Additional properties not allowed: schema at #/properties/value
      Missing required property: $ref at #/properties/value
    Missing required property: $ref at #/components/schemas/NISE

JSON_OBJECT_VALIDATION_FAILED

Any insight on this issue?

Lastly, I've tried with some simple openapi3.0 yaml files in the same way and it's working without any issue.

Examples which I've tried

main.yaml

openapi: 3.0.1
info:
  title: ping test
  version: '1.0'
servers:
  - url: 'http://localhost:8000/'
paths:
  /some/ping:
    get:
      operationId: pingGet
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: './other.yaml#/SomeObj'
components:
  schemas: {}

other.yaml

SomeObj:
  properties:
    s1:
      type: string
    s3:
      type: string

This simple example works without issue. i.e $ swagger-cli validate main.yaml outputs: main.yaml is valid

Looking forward to hearing soon & thanks for spending time to look into this descriptive question.

Arslan

Answer 1

The way in which you are trying to refer to the schema defined in the violation_schema.yaml from simple_violation_bool.yaml is not correct . You do not need to define $ref: './violation_schema.yaml#/NISE' line at against each property defined in the simple_violation_bool.yaml file . Also , since you are defining schema altogether in a different schema file violation_schema.yaml , you do not need to define all those values again in the simple_violation_bool.yaml,i.e id,name,ports,value,etc.. Let's try to understand in a simple way , lets say you were not defining a separate file for the schema, but referring it from within the same file , i.e simple_violation_bool.yaml, then in that case things will look something like this as below :

So ,based on below observation , i corrected your yaml files and now its validating properly .

simple_violation_bool.yaml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: simple_violation_bool
  license:
    name: MIT
  description: |
    Simple violation in simple_violation_bool module
externalDocs:
  description: NISE simple_violation_bool.
  url: "https://simple_violation_bool.net"
servers:
  - url: https://swagger.io/specification/
paths: {}

components:
  schemas:
    ROOT:
      type: object
      title: The Root Schema
      $ref: 'violation_schema.yaml#/NISE'

violation_schema.yaml

  NISE:
      required:
        - description
        - id
        - name
        - ports
      properties:
        description:
          type: string
          title: The Descripton Schema
        id:
          type: integer
          title: The Id Schema
          default: 0
          format: int64
        name:
          type: string
          title: The Name Schema
        ports:
          type: array
          title: The Ports Schema
          items:
            type: integer
            title: The items Schema
            default: 0
        value:
          type: object
          title: The Value Schema

swagger-cli validate simple_violation_bool.yaml

simple_violation_bool.yaml is valid

I hope that it resolves the issue for you . Let me know if that helps !!