Skip to content

Overlay output sometimes includes unexpected YAML anchors #708

@hkosova

Description

@hkosova

CLI version: bump-cli/2.9.5 darwin-arm64 node-v20.18.0

I'm trying to use an overlay to bulk set the same example value for multiple schema properties in an OpenAPI 3.1 YAML spec. The output unexpectedly includes YAML anchors and aliases (&ref_0, *ref_0) in the added example value - even though the input OpenAPI and the overlay do not use any anchors/aliases.

Is there any way to prevent YAML anchors/aliases being used in the output from the overlay command? Not all OpenAPI tools support YAML anchors.


The repro conditions seem to be:

  1. target that matches multiple nodes (e.g. using a * wildcard operator or a union operator)
  2. update value containing an array of objects
OpenAPI spec
openapi: 3.1.0
info:
  title: test
  version: 1.0.0
paths: {}
components:
  schemas:
    User:
      type: object
      properties:
        metadata:
          type: object
    Company:
      type: object
      properties:
        metadata:
          type: object

Overlay:

overlay: 1.0.0
info:
  title: test overlay
  version: 1.0.0

actions:
  - target: $.components.schemas['User', 'Company'].properties.metadata
    # Same issue with
    # target: $.components.schemas.*.properties.metadata
    update:
      examples:
        - one: two

Expected result:

...
    User:
      type: object
      properties:
        metadata:
          type: object
          examples:
            - one: two   # <-----
    Company:
      type: object
      properties:
        metadata:
          type: object
          examples:
            - one: two   # <-----

Actual result:

...
    User:
      type: object
      properties:
        metadata:
          type: object
          examples:
            - &ref_0   # <----- ???
              one: two
    Company:
      type: object
      properties:
        metadata:
          type: object
          examples:
            - *ref_0   # <----- ???

Workarounds

The following overlays do NOT cause the issue:

  1. Using multiple targets/actions instead of a single bulk target.

    actions:
      - target: $.components.schemas.User.properties.metadata
        update:
          examples:
            - one: two
      - target: $.components.schemas.Company.properties.metadata
        update:
          examples:
            - one: two

    Not really a good option for us because we'd like to avoid copy-pasting. (The repro is a simplified example, our actual examples values can have a dozen of lines.)

  2. Adding example (singular) instead of examples (array of examples).

      - target: $.components.schemas['User', 'Company'].properties.metadata
        update:
          example:
            one: two

    Also not a good option; we specifically want to use examples because example in schemas has been deprecated in OpenAPI 3.1.

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions