A reference to something should always be a JSON pointer and not a name (security scheme example)

[arno-di-loreto]

In v3, some "reusable" elements are referenced by name instead of using a JSON pointer reference: security schemes (and their scopes), or tags for instance.

in v4, A JSON pointer reference should be the only way of referencing something:

• that makes the spec consistent (always referring to a component in the same way)
• allows defining locally some elements that weren't
• allows referencing externally some elements that weren't

Here's how it would work for security schemes (did not yet looked how it would work for scopes):

v3

security:
  fooSecurity:
    # scheme usage + optional configuration
components:
  securitySchemes:
     fooSecurity:
     # scheme definition

V4 proposal

security:
  - securityScheme:
      $ref: '#/components/securitySchemes/fooSecurity' # security scheme could be defined locally
    securityRequirements: # just using the original object name, could be something else
      # scheme usage + optional configuration
components:
  securitySchemes:
     mySecurityScheme:
     # scheme definition

PS: Speaking of security, we could also have reusable securityRequirements (but that's another discussion)

[jugaadi]

Discriminator too?

[kevinswiber]

We should look at deprecating discriminator in favor of a built-in JSON Schema approach.

[handrews]

propertyDependencies (which will be in the next JSON Schema release) solves most of discriminator. Some additional hinting is probably needed regarding the class name, as discriminator allowed that to diverge from the property value, but that's easily accomplished with annotations as part of a code gen library.

[handrews]

Note that there is a large conversation about referencing happening over at AsyncAPI, and while there are things involved there specific to AsyncAPI, it is very much relevant to OpenAPI (and JSON Schema) as well.

[handrews]

Note that AsyncAPI is now fixing this for security schemes.

[handrews]

We're now considering going in the other direction - things should be component names and not JSON Pointers (although within JSON Schema that will only change if JSON Schema does):

• Imports proposal #72
• Handling JSON Schema referencing in Moonwalk #73