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

Question

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?

Answer 1

$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.

• [WIP] Alternative OAS3 JSON Schema (link to schema)
• OpenAPI v3 JSON Schema (link to schema)