Reference objects for update property

[adamaltman]

Can a reference object ($ref) be used for the update property?

update	Any	An object with the properties and values to be merged with the object(s) referenced by the target. This property has no impact if remove property is true.

The reason I ask is that people struggle with the OpenAPI format itself. Take overlays and it adds an extra level of complexity. The spec seems silent about it and I'm unclear if Any allows for reference object usage.

I would like to be able to use the overlay like this:

overlay: 1.0.0
info:
  title: Structured Overlay
  version: 1.0.0
actions:
- target: "$"   # Root of document
  update:
    $ref: ./my/changed/openapi.yaml

Why? Because I could use my knowledge of OpenAPI, existing OpenAPI authoring tooling, and not need to learn anything new other than this little snippet I copy and paste into its own separate overlay.yaml file.

[ralfhandl]

@adamaltman The update object in this example is valid.

It would be merged with the target document, resulting in a document that has a $ref field in the root object if the target document represents a single JSON object.

If that target document was a valid OpenAPI description, then the end result is not a valid OpenAPI description, as the OpenAPI Object does not allow $ref.

[jeremyfiel]

Just to clarify the expected output from Ralf's answer..

The OP request would output invalid OpenAPI

openapi: 3.0.4
info:
  title: test
  version: 0.0.1
paths: {}
$ref: './my/changed.openapi.yaml'  # this is the invalid piece that would be defined.  The `update` is a merge, not a replace.