Proposal - add support for sourcing an update value from another node of the document

[baywet]

Hey everyone,
Thank you for putting this together, overlays are extremely helpful for cleaning up OAI descriptions owned by third parties.

One scenario we can across multiple times is the use of oneOf to specify nullability with something like this:

components:
  schema:
    Foo:
      oneOf:
        - type: string #using string here for simplicity, but you could imagine a complex object type being described instead
        - nullable: true

In our scenario, we're importing OAI descriptions to mechanically process them down the road (doc generation, code generation, etc...). When the tool downstream sees that pattern it "jumps to conclusions" and emits a union type. Although that's technically correct, it's incorrect in principle. We could of course change that tool and add a bunch of specialization conditions to say "sure, but if you see that pattern, it's not really a union type".

To clean it up before processing, we end up with an overlay that looks something like this

{
  "actions": [
    {
      "update": {"type": ["string", "null"]},
      "target": "$.components.schemas['Foo']"
    },
    {
     "target": "$.components.schemas['Foo'].oneOf",
     "remove": true
    }

Although that works, it leads to a lot of duplication we have to maintain (again, imagine that instead of type string, you have a complex object definition with a bunch of properties, etc...)

We'd much rather have the following overlay instead.

{
  "actions": [
    {
      "update-from-source": "$.components.schemas['Foo'].oneOf.[? (@.type == 'string')]",
      "target": "$.components.schemas['Foo']"
    },
    {
     "target": "$.components.schemas['Foo'].oneOf",
     "remove": true
    },
    {
     "target": "$.components.schemas['Foo']",
     "update": {"type": ["string", "null"]}
    }

A couple of notes on that example:

• yes, it's technically more actions, but now the only thing I have in the update, is the type field, no duplication for the rest of the schema.
• I gave an ugly name to that new "update-from-source" new action kind so we can give it a better name together.
• This new action would effectively behave like update behaves, but source the update value to merge into the target using a JSON Path instead of a "hardcoded" value.
• I think we'll need to define the behaviour as "source the update value first, and entirely, then apply the update" to prevent infinite recursion kind of problems.

If this new thing is desirable, I'm happy to draft something up, and potentially have it released as part of a 1.1 version of the spec.

[lornajane]

@baywet I think this is pretty close to a few of the other discussions that have been going on in the group. Could you take a look at #121 for some use cases - and read all the way to the end for a proposed implementation that uses existing content from an OpenAPI description as the update value.

I'm not sure I quite understand what the update-from-source action does in your example, maybe you could show a before and after of OpenAPI snippets to make it more obvious what's going on?

[baywet]

@lornajane thanks for chiming in. I think that both this and the 121 proposal are similar ways to achieve very similar results functionally speaking.
With my previous examples, the result would be:

components:
  schema:
    Foo:
      type: [string, "null"]

Essentially the "update-from-source" is equivalent to the "update" property, except that instead of containing a "hardcoded" update value, it copies a JSON Node from the document we're processing, making the value dynamic.

Let me know if you have any additional comments or questions.

[baywet]

To be more explicit, if I break down a step by step of the 3 actions, with a more concrete example:

Given the following actions

{
  "actions": [
    {
      "update-from-source": "$.components.schemas['Foo'].oneOf.[? (@.type == 'object')]",
      "target": "$.components.schemas['Foo']"
    },
    {
     "target": "$.components.schemas['Foo'].oneOf",
     "remove": true
    },
    {
     "target": "$.components.schemas['Foo']",
     "update": {"type": ["object", "null"]}
    }

initial state

components:
  schema:
    Foo:
      oneOf:
        - type: object
          properties:
            prop1:
              type: string
        - nullable: true

action 1 - update from source

components:
  schema:
    Foo:
      type: object
          properties:
            prop1:
              type: string
      oneOf:
        - type: object
          properties:
            prop1:
              type: string
        - nullable: true

action 2 - removal of the extra of the oneOf node

components:
  schema:
    Foo:
      type: object
          properties:
            prop1:
              type: string

action 3 - update of the type

components:
  schema:
    Foo:
      type: [object, "null"]
          properties:
            prop1:
              type: string

The main benefit here is that I didn't have to duplicate all the definition in the first oneOf entry into the overlay like this:

{
  "actions": [
    {
      "update": { "type": ["object", "null"], "properties": { "prop1": {"type": "string"}}},
      // I'm trying to avoid maintaining another copy here which will become stale over time
      "target": "$.components.schemas['Foo']"
    }
 ]
}

[baywet]

To capture some notes from the meeting, this syntax would be the equivalent for that example

overlay: 1.1.0
info:
  title: Re-use a response for another content type
  version: 1.0.0
actions:
  - target: '$.paths["/item"].post.requestBody.content'
    update: {"application/yaml": true}
  - target: '$.paths["/item"].post.requestBody.content["application/yaml"]'
    update-from-source: '$.paths["/item"].post.requestBody.content["application/json"]'

[baywet]

Additionally, this syntax makes it easy to:

• validate any conflict with existing "verbs" (remove, update, etc...)
• implement a peer for environment variables (with the ugly provisional name of "update-from-env", value would be the environment variable name)