-
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
Clarify the behavior of YAML comments in Overlays #83
Comments
Thomas's comment in a slack thread caused me to check the OpenAPI Specification to see what we say about YAML comments there, and it turns out we don't say anything about them. That makes some sense to me, as I wouldn't expect converting YAML > JSON > YAML would preserve a comment. However, Overlays feels a little bit different in that you could apply YAML to YAML and end up losing your YAML comments. Isn't that a small surprise? |
My feelings are that:
|
It's worth noting that many YAML packages do not preserve comments, or require great contortions to access them. Here is a thread on comments in PyYAML, the de-facto Python standard for working with YAML (and fastest by a large margin despite the claims of other libraries- I tested a bunch of them). Therefore, I don't think it's reasonable for any of our specifications to mandate YAML comment-preservation behavior. It's simply not going to be interoperable. I think this strengthens the argument that, even when using a comment-preserving parser, comments from the overlay should be treated as commenting on the overlay and not as commenting on the target. That makes the behavior between comment-preserving and non-comment-preserving parsers more similar. I see this as analogous to preservation of line numbers: That's not something any OpenAPI specification (little-s, generic, not just OAS) should mandate. Not only do many parsers not track them, but the ones that do are generally orders of magnitude slower. |
Also, while that thread about PyYAML mentions an alternative package, keep in mind that in many environments, incorporating a new package into code is an extremely heavy-weight process requiring both legal and security review. Anything we mandate needs to work with the most common libraries and not require something unusual. |
The Overlay Specification should clarify how YAML comments work. Some things to consider:
The text was updated successfully, but these errors were encountered: