CODEWITHSUNDEEP
openapijson-schema-validator
Eugen Konkov
Eugen Konkov

Reputation: 25223

Why OpenAPI does not define '$ref' as allowed property?

In compare to draft-07 it defines:

{
    "type": ["object", "boolean"],
    "properties": {
        ...
        "$ref": {
            "type": "string",
            "format": "uri-reference"
        },
    }
    ...
}

Currently I am trying to write validator for openapi. But validation fails because openapi schema (yes, it is schema from google apis) does not define $ref as allowed property for schema.

Is this a typo? What is recommendation about how to check $ref property?

Upvotes: 3

Views: 3572

Answers (1)

Helen
Helen

Reputation: 97962

$ref is a JSON Reference. It's not part of the schema definition, instead it's part of the reference definition:

"reference": {
  "type": "object",
  "description": "A simple object to allow referencing other components in the specification, internally and externally.  The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules.   For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.",
  "required": [
    "$ref"
  ],
  "additionalProperties": false,
  "properties": {
    "$ref": {
      "type": "string"
    }
  }
},

And then other definitions where $ref is allowed use oneOf something or reference (example):

"schemaOrReference": {
  "oneOf": [
    {
      "$ref": "#/definitions/schema"
    },
    {
      "$ref": "#/definitions/reference"
    }
  ]
},


By the way, there are currently two different draft OAS3 JSON Schemas in the official OpenAPI Specification repository. Feel free to try them instead, and provide your feedback in the corresponding discussions.

Upvotes: 2

Related Questions