Feature: Add support for overlays

[baywet]

the overlay specification is getting close to its final version. It'd be nice to implement the specification in the library so client applications can take advantage of it for thing like generic errors and such.
The solution should be implemented in a separate package this one takes a dependency on, so people can use this functionality outside of openAPI. But the code can be collocated here.

[darrelmiller]

This issue microsoftgraph/msgraph-metadata#124 is dependent on overlays.

[CarolKigoonya]

• An object model for the overlay document
• Overlay reader class & a set of deserializers
• Implement the overlay service
• Obtain json path support

Unknowns

• where does the code live? Open API library or in its own package
• Do we implement or use existing json path
• how do we model the update property

[darrelmiller]

I don't feel strongly about whether we should create a new project or not. However, I suspect we will re-use the OpenApiAny types and the ParseNode classes in the reader, so I think it would be easier if it is all part of the same library. In theory the an Overlay could be used to apply to any JSON/YAML document, however, I think we should scope our efforts to just updating OpenAPI documents.

I believe because of this issue OAI/Overlay-Specification#8 we are probably going to have to implement our own JSONPath querying.

The update property could be implemented as type IOpenApiAny. This will allow a user to create an overlay either with just simple OpenApiObject/OpenApiArray structures, or with any existing OpenAPI model object.

An overlay object might be created like this.

var overlay = new OverlayDocument();
overlay.Info.Title = "Structured Overlay";
overlay.Info.Version = "1.0.0";

var action = new OverlayAction();
action.Target = "$" // JsonPath, not JMESPath
action.Update = new OpenApiDocument() ;  // If we allow OpenAPI model elements, how do we distinguish between default values and set values?  Should we only use OpenApiObject/OpenApiArray so that changed values are explicit?  

overlay.Actions.Add(action);

https://github.com/OAI/Overlay-Specification/blob/main/versions/1.0.0.md#structured-overlays-example

[darrelmiller]

Upon further discussion we believe that accepting strongly typed OpenAPI objects is not going to work.

Instead we should limit the update property to only accept OpenApiArray, OpenApiObject and OpenApiPrimitive.

overlay: 1.0.0
actions:
 - target: "$.*.get.parameters[name=='top']"
   update: 
     required: true

var overlay = new OverlayDocument();
var action = new OverlayAction() {
   Target = "...",
   Update = new OpenApiObject() {
      [["required"],[true]]  // With the correct c# syntax  :-)
   }
}