Libopenapi doesn't support YAML 1.2 Anchors and Aliases

[TristanSpeakEasy]

We have a customer using anchors and aliases extensively in their OpenAPI documents, and have discovered libopenapi doesn't support these.

The type of errors we get are failed to build model: array build failed, input is not an array, line 22800, column 17

Looking at https://pkg.go.dev/gopkg.in/yaml.v3 the underlying YAML parser does support Anchors and Aliases ie https://github.com/go-yaml/yaml/blob/v3.0.1/yaml.go#L397 but it looks like AliasNode isn't handle in the library.

I believe this is totally valid usage of the OpenAPI specification due to its callout of support YAML 1.2 https://spec.openapis.org/oas/v3.1.0#format

[daveshanley]

I've not spent much time with Alias and anchors, but yes, I agree it should be supported. Adding to the backlog.

[daveshanley]

Do you have any examples of specs using anchors and aliases?

[TristanSpeakEasy]

openapi: 3.0.0
info:
  version: 1.0.0
  title: Example API
servers:
  - url: https://api.example.com
    description: production server
security: &security
  - Jwt: []
  - Token: []

x-common-definitions:
  life_cycle_types: &life_cycle_types_def
    type: string
    enum: ["Onboarding", "Monitoring", "Re-Assessment"]
    description: The type of life cycle
  default_read_errors:
    &default_read_errors # The typical errors we might return on a simple read operation
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/PermissionDenied'
    '404':
      $ref: '#/components/responses/NotFound'
    default:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  default_security: &default_security
    - Jwt: []
    - Token: []

paths:
  /alerts:
    get:
      tags:
        - Alerts
      description: List of Alerts
      operationId: AlertsList
      security: *security
      parameters:
        - name: life_cycle_type
          description: Includes additional alert details
          in: query
          schema:
            <<: *life_cycle_types_def
      responses:
        <<: *default_write_errors
        '200':
          description: Summary of alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alerts'
components:
  schemas:
    Alerts:
      type: object
      properties:
        alerts_count:
          type: integer
          description: Total number of alerts
          readOnly: true

[daveshanley]

OK, thank you. I'll need to dig into this a little more. If the raw data is there in the Node then it should be supported - I just need to figure out where that logic would live

[ThomasRooney]

Another upvote for this. Here's another example, with slightly different syntax:

openapi: 3.0.2
info:
  title: Example
  version: 0.0.1
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
    Example:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          title: Name
          pattern: ^[a-zA-Z0-9_\-]+$
          description: Name of the Example.
        description:
          type: string
          title: Description
          description: Brief description of this Example. Optional.
security:
  - bearerAuth: []
paths:
  /system/Examples:
    get:
      tags:
        &a1
        - Examples
      summary: Get a list of Example objects
      description: Get a list of Example objects
      responses:
        &a2
        "200":
          description: a list of Example objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: number of items present in the items array
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Example"
        "401":
          description: Unauthorized
        "500":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      tags: *a1
      summary: Create Example
      description: Create Example
      requestBody:
        description: New Example object
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Example"
      responses: *a2

[daveshanley]

I will start looking at this shortly.

[daveshanley]

v0.9.3 now supports anchors and aliases, as well as yaml node merging.

I have tried to capture everywhere this may occur, but I could have missed a few spots. @ThomasRooney @TristanSpeakEasy, can you verify this new version captures all the aliases, anchors and merges?

[ThomasRooney]

Looks good in my testing with a couple of large documents with large numbers of aliases, anchors and merges.

Thanks!