Resolution rules of following OAS documents

[char0n]

Hello all,

I was wondering if authors of the spec could help me verify the resolution behavior of following use-cases. foo and bar are pointing to future values of SharedResponse schema. I'm interested if this is correct or incorrect usage of the spec.

In OAS 3.0.0 JSON Reference spec is used to resolve the values. JSON Reference delegates the identifier fragment resolution to JSON Pointer spec.

openapi: 3.0.0
info:
 description: 
 version: 1.0.0
 title: Whatever
components:
 schemas:
   PartOfMySharedResponse:
     type: "object"
     properties:
       foo:
         $ref: '#/components/schemas/SharedResponse/properties/foo' 
       bar:
         $ref: '#/components/schemas/SharedResponse/properties/bar'  
   SharedResponse:
     $ref: '//example.com/shared.yaml#components/schemas/MyResponseDefinitionWithFooAndBarProperties'

In OAS 3.1.0 we have special Reference Object driven by RFC3986 and JSON Pointer. Then we have JSON Schema 2020-12 $ref keyword with it's own rules of resolution.

openapi: 3.1.0
info:
 description: 
 version: 1.0.0
 title: Whatever
components:
 schemas:
   PartOfMySharedResponse:
     type: "object"
     properties:
       foo:
         $ref: '#/components/schemas/SharedResponse/properties/foo' 
       bar:
         $ref: '#/components/schemas/SharedResponse/properties/bar'  
   SharedResponse:
     $ref: '//example.com/shared.yaml#components/schemas/MyResponseDefinitionWithFooAndBarProperties'

Thanks for help!

[karenetheridge]

There are a number of (presumably?) typographical errors in the example which makes it hard to tell what you're intending:

• is the URI of the document itself is intended to be //example.com/shared.yaml?
• #components/... is not a valid fragment for a uri-reference in any version of the spec. I'll assume that this is a typo and you intended to include a / after the leading #, making the fragment a valid json pointer.
• and then, the schema corresponding to json pointers /components/schemas/MyResponseDefinitionWithFooAndBarProperties doesn't exist in either schema. Did you intend this to be PartOfMySharedResponse instead?

But reading all these fixes into your examples... the schemas being referenced by the $ref do not exist. Referenced schemas do not "replace" the $ref keyword - they are more like a pointer in C or other languages, that jump to an entirely different location in the document, and the referenced json pointer must actually exist in the target location.

[karenetheridge]

I just noticed you also asked this on json-schema-org/community#61. Please could you include cross-links when doing this -- it saves duplicated effort, and lets other people find answers when searching.

[webron]

He did here... 😀

[handrews]

Given the lack of further comment I'm considering this resolved enough to close, but I'll also note: The URI-reference resolution rules (how to construct a full URI, starting with a scheme like https:, from a relative URI-reference) are the same in all vesions of all specifications. Draft 2020-12 changes exactly how one uses the reference schema, but that only has user-visible impact when there are adjacent keywords, which is not the same here.