Improve type safety with restricted component references (OAS 4 proposal)

[vearutop]

JSON Schema does not define a concept of $ref usage in data values, neither it provides a way to ensure if resolved data value is valid. Nevertheless using $ref in data is popular and is used in OpenAPI.

If it is not possible to validate the resolved value, we can at least have best effort validation that reference leads to a correct place.

OpenAPI spec since v3 has a pre-defined place to store some kinds of referenced values: components.

For example responses are defined as follows:

      responses:
        type: object
        patternProperties:
          '^[a-zA-Z0-9\.\-_]+$':
            oneOf:
              - $ref: '#/definitions/Reference'
              - $ref: '#/definitions/Response'

The problem here is that current schema allows $ref to lead to any place, not only to #/components/responses/....

Semantically incorrect (but valid) schema with confused references:

paths:
  /pets:
    get:
      parameters:
        - $ref: "#/components/responses/UnexpectedError"

We can make it harder to go wrong by restricting local references of schema components, for example ResponseReference:

  ResponseReference:
    type: object
    required:
      - $ref
    patternProperties:
      '^\$ref$':
        type: string
        format: uri-reference
        oneOf:
          - pattern: '^#/components/responses/'
          - not:
              pattern: '^#/'

Such restriction (pattern: '#/components/responses/') could also be employed for external references, though it may have too much of negative impact on flexibility.

[handrews]

I think there are three things here:

1. References within the Schema Object - these are defined by JSON Schema, not OpenAPI
2. References outside of the Schema Object - these are already required to point to the right type of object
3. Enforcing reference target types through schema validation of the OpenAPI Description - we have generally avoided trying to do such complex validation in the schema

The OASComply project will eventually validate this sort of referential integrity, and there are plenty of linters that I believe can also do this. Non-JSON Schema referencing will be completely revamped in OAS 4 Moonwalk in a way that I believe will make this moot.

Since we've already declined to enforce this more strictly in OAS 3 in the past, and it's moot in OAS 4, I'm going to close this.