OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Add appendix "Informative references" to published spec documents
Check existing non-RFC links whether they are normative or informative, for example links to the YAML specification, or links to the JSON Schema specifications.
Add appendix "Informative references" for selected external links that we deem non-normative and worth mentioning.
For those wondering why this is in "Automation & Infrastructure", the "Normative References" appendix seems to be added by the HTML generation script- it is not present in our (allegedly normative) Markdown document. Which strikes me as odd- are not normative references a normative part of the spec?
Just noted this inconsistency:
The Markdown spec source already has an "Appendix A" with the version history, which is rendered in HTML as chapter 5, and the normative references are added as second Appendix A.
The References section is being done by the Respec and it happens client-side. I have validated by checking the md2html script, which doesn't handle the references, and by checking the source code of the website. If you check it, you will see that this section is missing.
You can check the documentation of Respec here: https://respec.org/docs/#:~:text=ReSpec%20uses%20the%20context%20of,reference%20is%20treated%20as%20normative.
In the md2html that tries to fix some links. Maybe we could use the same functionality.
ReSpec has syntax for informative references. We don't consistently use its syntax for references, and we possibly should. That might be more predictable than relying on inferences and heuristics.
Discussion concludes that the OpenAPI Learn is the only informative link from the collection
I think we might to also add the RFC describing URIs (3986?) because although "format": "uri" is managed by JSON Schema, we do also have URI references (via $ref) in OpenAPI itself. Although, this could be considered covered by "an openapi schema must be valid according to the JSON Schema specification here".
we might to also add the RFC describing URIs (3986?)
That is already listed in the Normative References: https://spec.openapis.org/oas/latest.html#bib-rfc3986
@karenetheridge: anything else to do here?
Yes, sorry, I called it out because I didn't see it in the candidates list at the top of this issue.