Improvement: Provide a way to determine where a reference lives

[TristanSpeakEasy]

Consider this:

• A top level openapi.yaml references an external ref from one file otherfile.yaml#/components/schemas/reference1 and another otherfile2.yaml#/components/schemas/reference2

Those files might look like:

otherfile.yaml

components:
  schemas:
    reference1:
      type: array
      items:
      	$ref: '#/components/schemas/item'
    item:
      type: object
      properties:
        field:
          type: string

otherfile2.yaml

components:
  schemas:
    reference2:
      type: object
      additionalProperties:
      	$ref: '#/components/schemas/item'
    item:
      type: object
      properties:
        otherfield:
          type: string

The problem is when iterating through the schemas we will eventually come across the item from otherfile.yaml and the item from otherfile2.yaml and we may try and use .ParentProxy.GetSchemaReference() on the schema to get its "reference" this will return #/components/schemas/item for both these item schemas and these references may be used to determine their identity but with this there is no way to distinguish them as different references.

It would be good to somehow be able to determine where the schema came from so we can "fully resolve" the reference to otherfile2.yaml#/components/schemas/item to ensure they are unique

[daveshanley]

This has been on my mind for a while. I have a few use-cases in mind that need this type of upgrade. There needs to be an upgrade to the way indexes track which files they were created from, and where in the tree they sit.

[TristanSpeakEasy]

Something like .ParentProxy.GetReferenceFile() or having an option to always fully resolve the .ParentProxy.GetReference() so it always returns ./components.yaml#/components/schema/user the reference with the file it was resolved from at the front of the reference

[daveshanley]

Added in v0.13.12

A new method GetReferenceOrigin() exists on SchemaProxy that returns *index.NodeOrigin

type NodeOrigin struct {
  // Node is the node in question 
  Node *yaml.Node

  // Line is yhe original line of where the node was found in the original file
  Line int

  // Column is the original column of where the node was found in the original file 
  Column int

  // AbsoluteLocation is the absolute path to the reference was extracted from.
  // This can either be an absolute path to a file, or a URL.
  AbsoluteLocation string

  // Index is the index that contains the node that was located in.
  Index *SpecIndex
}

Let me know if you have any issues with it.