Extra fields in the presence of $ref

[Geod24]

I recently started to implement an OAI parser in D, and immediately hit an issue with my first test case, the Gitlab openapi.yml.

As it turns out, it has ref to the root of the document, outside of components (#2038):

# Other OpenAPI Object fields... 
paths:
  # METADATA
  /v4/metadata:
    $ref: '#/metadata'

  # VERSION
  /v4/version:
    $ref: '#/version'

  # More...
metadata:
  get:
    tags:
      - metadata
    summary: 'Retrieve metadata information for this GitLab instance.'
    operationId: 'getMetadata'
    # More stuff...

version:
  get:
    tags:
      - version
    summary: 'Retrieve version information for this GitLab instance.'
    # More stuff...

This works with the swagger inspector but not with the ruby library, for example:

irb(main):008:0> document = Openapi3Parser.load_url("https://gitlab.com/gitlab-org/gitlab/-/raw/master/doc/api/openapi/openapi.yaml")
=> Openapi3Parser::Document(openapi_version: 3.0, root_source: Openapi3Parser::Source(input: https://gitlab.com/gitlab-org/gitlab/-/raw/m...
irb(main):009:0> document.valid?
=> false
irb(main):010:0> document.errors
=> Openapi3Parser::Validation::ErrorCollection(errors: {"#/"=>["Unexpected fields: metadata, version, accessRequestsProjects, accessRequestsProjectsApprove, accessRequestsProjectsDeny, accessRequestsGroups, accessRequestsGroupsApprove, accessRequestsGroupsDeny, accessTokens and accessTokensRevoke"], "#/paths/%2Fv4%2Fprojects%2F%7Bid%7D%2Faccess_tokens/%24ref"=>["#/accessTokens does not resolve to a valid object"]})

From reading the specs, this should not be allowed: the fields do not match the Specification Extensions and do not match the name of field in the OpenAPI Object.

Could someone confirm that this is indeed a bug ?

[hkosova]

From reading the specs, this should not be allowed: the fields do not match the Specification Extensions and do not match the name of field in the OpenAPI Object.

Correct.

The Ruby parser is right to report those extra root-level fields as errors.

The GitLab definition can be made valid either by adding the x- prefix to those extra fields:

paths:
  # METADATA
  /v4/metadata:
    $ref: '#/x-metadata'   # <---

  # More...
x-metadata:   # <---
  get:
    tags:
      - metadata
    # More stuff...

or by replacing that structure with inline definitions:

paths:
  /v4/metadata:
    get:
      tags:
        - metadata
      # More stuff...

[handrews]

This was answered, closing.