Comments (10)
I think we should not update in patch releases, in case there's an impacting change. We reference enough 3rd party docs that it would be significant work to review if any of their wording change could possibly impact ours. Let's stick to doing that in minor versions, would be my recommendation. (with the proviso that all rules can be broken if there are good reasons!)
from openapi-specification.
@dret we don't change the published specs (except when something happens like GitHub breaking their own markdown rendering, but in that case we're changing a broken link to work again, not changing the actual contents).
It's not clear to me if updating obsoleted RFCs is something we do in patch releases or if we want to leave those and only change them in a minor release. Process issues related to this:
- #3528
- #3529
- #3785
- #1778 (@dret if you have any idea whether we really need to mention that 3986 obsoletes 1738 since we cite 1866 which cites 1738, that would be really helpful as I've thought myself in circles on it and no one else here seems to know)
from openapi-specification.
if somebody can point me at some "here's how to change the OpenAPI spec" primer, I'd be more than happy to give it a try.
We're kind of buried in a backlog of issues trying to define and document this:
from openapi-specification.
from openapi-specification.
not the latest HTML spec
I didn't make this reference, so I don't know, but I assume because it's actually in WHATWG's URL "Living Standard" which doesn't even acknowledge the existence of relative URI-references [EDIT: as a syntax independent from a browser-supplied base URI], among many other failures to cover 3986, which claims to "obsolete". And then the author refuses to define relative references because, (and I quote) there is a "lack of browser-related use cases" 🤦
Plus, WHATWG specs are pseudocode tied to browser implementations. They're completely unreadable for anyone else IMNSHO.
While I've been working on the parameter serialization areas, I have debated mentioning WHATWG. But to me, referencing WHATWG URL in an API spec that's based off of RFC3986 is asking for trouble. It introduces a conflicting set of terminology, a dismissive attitude of the work of past spec authors, and an aggressively browser-centric worldview that outright dismisses the utility or relevance of any other context at all.
from openapi-specification.
To be clear: I think the WHATWG specs do a valuable thing by standardizing implementation concerns. If they just did that on top of the existing RFCs and W3C specs that define grammars, syntax, and semantics, it would have been fanstatic. But instead they act like those other concerns, audiences, and environments are so unimportant that they refuse to address them while attempting to prevent anyone else from doing so. We're an API spec, not a browser spec, so we are solidly outside of what they consider valid or relevant, as they've made clear over and over.
from openapi-specification.
Oh and WHATWG URL's encoding set for application/x-www-form-urlencoded
is different from RFC6570's form expansion operator, and I can't figure out how to explain that in our spec with out a multi-paragraph digression, and I just do not have any idea how to deal with that (despite my ranting, if someone comes up with a coherent way to refernce and explain all of that, I would happily support. I'm just at a loss with it)
from openapi-specification.
from openapi-specification.
@dret thanks – my reaction was probably excessive so I apologize for that. Honestly, it's mostly that I don't know what to do with the mess. There's just no good answer.
Anyway, if you want to keep this focused on 7231 vs 9110 you're welcome to hide or delete this digression (or if you don't have permissions, lmk and I'll do it), or close this and re-file the main point.
from openapi-specification.
@OAI/tsc review request: Should we replace obsoleted RFC references in patch releases, or can we only do that in a point release? They are obsoleted whether we update them or not, but idk how that's viewed in this context.
from openapi-specification.
Related Issues (20)
- Behavior of `allowEmptyValue: false` HOT 11
- Open Community (TDC) Meeting, Thursday 16 May 2024 HOT 2
- 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 the meaning of info.version HOT 15
- 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.