Incorrect schema object reference (OpenAPI 2.0)

Description

A schema’s $ref must point to a Schema Object defining the data structure. Referencing an entire response or parameter object does not match the model structure expected at that location.

Potential impact

Request or response types may not resolve, causing validation or model generation to fail.

Remediation

Reference the correct shared model under #/definitions/.... Valid external schema references are also allowed; check both the target’s object type and its data structure.

Examples

These POST examples replace the incorrect Success response reference inside schema with a reference to the User schema.

Before

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/responses/Success"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/limitParam"
          }
        ]
      }
    }
  },
  "responses": {
    "Success": {
      "description": "A user",
      "schema": {
        "$ref": "#/responses/Success"
      }
    }
  },
  "parameters": {
    "limitParam": {
      "name": "limit",
      "in": "body",
      "description": "max records to return",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}

After