Skip to content
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

Merged
merged 9 commits into from
Sep 13, 2024

Conversation

lornajane
Copy link
Contributor

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

versions/1.0.0.md Outdated Show resolved Hide resolved
versions/1.0.0.md Outdated Show resolved Hide resolved
versions/1.0.0.md Outdated Show resolved Hide resolved
versions/1.0.0.md Outdated Show resolved Hide resolved
versions/1.0.0.md Outdated Show resolved Hide resolved
@kevinswiber
Copy link

Thank you for doing this, @lornajane!

@ralfhandl ralfhandl added this to the Release 1.0 milestone Sep 9, 2024
versions/1.0.0.md Outdated Show resolved Hide resolved
Copy link
Contributor

@ralfhandl ralfhandl left a 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

versions/1.0.0.md Outdated Show resolved Hide resolved
versions/1.0.0.md Outdated Show resolved Hide resolved
mikekistler
mikekistler previously approved these changes Sep 10, 2024
Copy link
Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! 👍

ralfhandl
ralfhandl previously approved these changes Sep 10, 2024
@ralfhandl ralfhandl dismissed stale reviews from mikekistler and themself via 09700c3 September 10, 2024 16:10
Copy link
Contributor

@mikekistler mikekistler left a 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.

Comment on lines +11 to +12
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.
Copy link
Contributor

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) ...

Copy link
Contributor

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.

@kevinswiber @lornajane?

Copy link
Contributor

@ralfhandl ralfhandl Sep 11, 2024

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

@ralfhandl ralfhandl merged commit 8e65fcf into OAI:main Sep 13, 2024
1 check passed
@lornajane lornajane deleted the docs/add-missing-sections branch September 13, 2024 13:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Write an introduction for the spec
5 participants