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

[handrews]

@arno-di-loreto Referencing Security Schemes with a URI (although not the $ref syntax) was added in OAS v3.2, while also still allowing the component name syntax. I believe the only thing that does not have a URI option is tag usage, where it was considered and rejected, at least for now. I don't quite recall why or whether it might be revisited later.

[arno-di-loreto]

@handrews Good news! For tags, I guess it's more complicated in the current state of v3 because the root-level tags holding tag definitions is a list. Using a $ref to identify a tag at the operation level would result in #/tags/1, which is not particularly meaningful and risks becoming invalid if the root tags are reordered. To enable using $refs for tags in V4, root tags should become an object (and we may consider moving it under components, but that's another concern).