Overlays Meeting (2024-09-10)

[lornajane]

All meetings are subject to the OpenAPI code of conduct. Please add your agenda topics if you have them!

[ralfhandl]

Release 1.0

• Clarify the update behaviour for arrays as well as objects #50
• Add an intro and other missing sections #47
• Clarify the version of JSONPath that's being used #49
• Which of these issues are relevant for Release 1.0?

Housekeeping

• Format markdown #51
• Should we add GitHub workflows for ... #53

[lornajane]

Thanks @ralfhandl for the agenda! I'll capture some of my notes from the session as comments here so we can discuss further as needed.

[lornajane]

An Overlay can be referred to as such since it is a noun (in comparison to an OpenAPI description which describes something, description is the noun). We will therefore use Overlay as a standalone word to mean some JSON or YAML that can be applied to an OpenAPI description. Overlay description is not in use as a term. Overlay Document could make sense to refer to a file with an Overlay in it, but is not formally defined.

[lornajane]

The Intro was updated to make better use of the term Overlay, and the Overlay term was edited in the specification, previously we referred to an "Overlay Document".

[lornajane]

Regarding how to refer to updates that target either objects or arrays, we updated the wording for that section again and removed the duplicate reference to how to replace an array since this is covered in the following paragraph. An example is also already included in the specification document.

[lornajane]

We reviewed the list of open issues and agreed that we don't have anything else that should be added to the 1.0 milestone. Some of the older existing issues can be revisited and closed around the time of the specification release.

[lornajane]

We believe that we are close to having the 1.0 release ready; this will then be open for a period to solicit feedback from current implementors before we publish. We also noted that everyone active in this project is also active in OpenAPI itself, which also has imminent patch releases coming up which will need our attention.