-
Notifications
You must be signed in to change notification settings - Fork 15
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add an intro and other missing sections #47
Conversation
…n since it is empty
Thank you for doing this, @lornajane! |
Co-authored-by: Ralf Handl <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1, minor nits only
Co-authored-by: Ralf Handl <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good! 👍
09700c3
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This mostly looks good, but I think we need to be clear about whether Overlays can be used on JSON or YAML docs other than OpenAPI descriptions.
The Overlay Specification is an extension or companion to the [[OpenAPI]] specification. | ||
An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we want to restrict Overlays to only operate on OpenAPI documents? For the most part the spec could easily be applied to any JSON or YAML doc. And in several places we seem to allow base documents of other types, e.g. target is described as
URL to the target document (such as an [[OpenAPI]] document) ...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The repo README.md says
The Overlay specification defines a way of creating documents that contain information to be merged with an OpenAPI description at some later point in time, for the purpose of updating the OpenAPI description with additional information.
Given that with RFC6902 and RFC7386 there are already two document formats for modifying arbitrary JSON documents, I'd keep to the original scope.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@mikekistler How about merging this PR and continuing the discussion in
We had some "TBD" sections, I removed one (data types, I don't think we can add this after so many people have implemented, and Overlays could span multiple OpenAPI versions!?!?), wrote an intro, and used a version of the Arazzo wording, acknowledging the retroactive nature of the 1.0.0 version specifically.
Hopefully this fills the main gaps! Fixes #44