Comments (15)
@dret I think the best we can do here is clarify in 3.0.4/3.1.1, and maybe in 3.2 we could make this field not required and add an apiVersion
field alongside it?
from openapi-specification.
from openapi-specification.
@dret as noted in discussion with @darrelmiller it really seems like version
is the version of the specific OpenAPI Description document, not the entire description. This is because an OpenAPI 3.1 document that is a complete document (includes an OpenAPI Object at the root) but only has components
(not paths
or webhooks
) will still have a required info
field with an Info Object, which will have its own required version
field. Such a components
-only document is expected to be shared by multiple APIs, each of which would have its Info Object and version
field in its own entry document.
So I think that's what we need to clarify. I don't see how any other definition of the version
field can work in 3.1. Once we accept either PR #3823 or PR #3855, it should also be a bit more clear how to handle document versioning and documents that are not complete.
from openapi-specification.
from openapi-specification.
@dret I'm just not sure how to say that it's not the API version any more clearly than we already do:
The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
from openapi-specification.
from openapi-specification.
For anybody interested in the final results of the poll, here they are:
from openapi-specification.
/info/version
is a valuable field for the implementation to know what version of the spec the document is written to adhere to, so it can know how to parse it. This is important to know as there are syntactic and behavioural differences between 3.0.x and 3.1.x, and these differences will grow over time with future revisions.
An implementation needs to know what assumptions the document author made when writing it, and to know how to parse the document. Removing it or making it optional allows implementations to give ambiguous or incorrect behaviour.
(edit: I mistakenly said /api/version in the copy of this that went to emai.)
from openapi-specification.
from openapi-specification.
@karenetheridge I think you're mixing #/openapi
(the version of OAS) and #/info/version
(the version of the document, which is meaningless to tools).
from openapi-specification.
Note that as far as API versioning goes, it's a complex topic with several issues open, mostly around the granularity of versioning.
from openapi-specification.
@dret I've updated PR #3861 with a fix removing "implementation" and rewording things a bit.
from openapi-specification.
Related Issues (20)
- Behavior of `allowEmptyValue: false` HOT 11
- Open Community (TDC) Meeting, Thursday 16 May 2024 HOT 2
- RFC 7231 has been obsoleted by RFC 9110 HOT 10
- Define a policy using draft PRs when waiting on specific approvals HOT 3
- Open Community (TDC) Meeting, Thursday 23 May 2024 HOT 5
- Open Community (TDC) Meeting, Thursday 30 May 2024 HOT 2
- We should not keep a minified version of respec.js HOT 1
- Document milestone usage in DEVELOPMENT.md
- Define and add new process labels and document general label usage in DEVELOPMENT.md
- Should `style: form` examples include `?` prefix? If so, what about `spaceDelimited`, `pipeDelimited`, and `deepObject`? HOT 4
- Simplify HTML rendering build process HOT 1
- Consolidated $ref-to-Some Object feature request
- Move examples to learn.openapis.org or spec.openapis.org HOT 5
- Preserve section links in ReSpec output HOT 2
- Open Community (TDC) Meeting, Thursday 06 June 2024 HOT 1
- Add dark mode support to the HTML versions of the OpenAPI specs HOT 3
- Clarify default dialect for referenced JSON Schema documents HOT 1
- Mention registry in the section defining extensions HOT 3
- Inconsistent or unclear string format : byte or base64 HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from openapi-specification.