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

Schema for 3.1 contains links to 3.1.0 specification #4181

Open
ralfhandl opened this issue Nov 8, 2024 · 5 comments · May be fixed by #4206
Open

Schema for 3.1 contains links to 3.1.0 specification #4181

ralfhandl opened this issue Nov 8, 2024 · 5 comments · May be fixed by #4206
Labels

Comments

@ralfhandl
Copy link
Contributor

The current schema for v3.1 contains comments pointing to the 3.1.0 specification:

$comment: https://spec.openapis.org/oas/v3.1.0#info-object

Should we

  1. Update these comments with every minor version, or
  2. Remove these comments`?
@karenetheridge
Copy link
Member

As I am the person that added them, I would much prefer updating them rather than removing them. I found references linking the main parts of the schema to the section in the specirication that described them to be quite useful when implementing my validation tool.

However, a simple "3.1.0" -> "3.1.1" search/replace won't do because some sections may have moved around in the document during the revision. This is why I identified a task item to go through and check these in the 3.1.1-dev issue that is now closed.

@handrews
Copy link
Member

We have a "latest" symlink (or copy?) for the spec, which is great because specs (unlike schemas) are primarily for humans. So we can use the "latest" URLs and then we just have to worry about updating the fragments. I did try to keep those as close to what they were as possible, and none of the Object sections will have changed. So that should be fine.

Going forward, we might need a "v3-1-latest", "v3-2-latest", etc. to make this work, though.

@ralfhandl
Copy link
Contributor Author

Should we use use symlinks instead of copies?

@handrews
Copy link
Member

@ralfhandl I don't actually know what we use right now but it seems fine whatever it is. I'm indifferent if someone wants to change it.

@ralfhandl
Copy link
Contributor Author

Please check

Not sure whether I prefer v3.1.html over v3.1-latest.html for the symlink name.

@karenetheridge @handrews Opinions?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants