Parameter objects included via `$ref`s break load for 3.0.x specs

[clarkenciel]

Reproduction here

OpenapiFirst#load throws an error on specs that include an OperationObject with a ReferenceObject as a parameter, e.g.:

# spec/parameters.yaml
id:
  name: id
  in: path
  required: true
  schema:
    type: string

# spec.yaml
paths:
  /test/{id}:
    get:
      operationId: test
      summary: example test
      parameters: 
        # this ref breaks load:
        - $ref: spec/parameters.yaml#/id

According to the spec for OperationObjects this should be valid and it works if the openapi version is set to "3.1.0".

[ahx]

Hi. Thanks for the report! I am seeing the issue on your test-repo 'URI::RFC3986_Parser#convert_to_uri': bad argument (expected URI object or URI string) (ArgumentError), but I don't know what is happening, yet.

[clarkenciel]

@ahx Yes that's the error I encountered originally. Apologies that I failed to include it in the original report.

[ahx]

Some details: So the issue is caused by the way we are creating sub-schema + parent-schema when following refs. The parent schema is needed to make relative $refs work. The error is raised when the parent schema is created. OpenAPI 3.0 uses JSON Schema Draft 4, where "id" is a keyword that "declares an identifier for the schema resource".
Even though we don't care about those when creating a parent-schema, we parse the parent-schema including {id: {name: … }} and that fails with json_schemer complaining that id is not a URI string.

@clarkenciel I don't know how to fix the issue yet, but as a workaround you could use a different key for your ref. Something other than "id" so that the ref changes to something else like - $ref: './spec/parameters.yaml#/idparam'. I know, it's not great, but handling refs is hard.

[clarkenciel]

Thanks so much for the investigation (and the gem!) @ahx. I think we can easily adopt that convention.

[ahx]

I still think this is a bug, so I have added a failing test here. Let's see what we can do about that.