OAI / OAI/Overlay-Specification

How to replace the value list of an array?

Open
#30 18 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
121
Forks
38
Avg merge
53m
Merged PRs (30d)
6

Description

I want to replace the value list of an array with a new list of values. However, the two overlay implementations I've tried treat the following example as "append to an array" rather than "replace an array".

I'm not sure if the implementation behavior is correct or a bug, so wanted to confirm the intended behavior with the spec authors.


OpenAPI document:

openapi: 1.0.0
info:
  title: Array replacement test
  version: 1.0.0
paths: {}
x-foo:
  x-bar:  # I want to replace all values of this array
    - 1
    - 2

Overlay:

overlay: 1.0.0
info:
  title: Array replacement test
  version: 0.0.1
extends: array-test.yaml

actions:
  - target: $['x-foo']
    update:
      x-bar:
        - 3
        - 4

The Action Object section says:

When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name

I understand this as x-foo being the "merge object", x-bar being a "property in the merge object", so the x-bar value from the overlay should replace (and not be appended to) the x-bar value in the document.


The workaround is to remove the array node then re-add it with the new values. This seems a bit verbose, but if that's the intended way to replace arrays then I'm OK with it.

actions:
  - target: $['x-foo']['x-bar']
    remove: true

  - target: $['x-foo']
    update:
      x-bar:
        - 3
        - 4

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Action Object section of the Overlay Specification and compare its merge wording with the provided OpenAPI and Overlay YAML examples. Confirm whether updating x-bar should replace or append the array, and document the intended behavior or the remove-and-readd workaround in the specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
yaml
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.