Add Security Considerations (3.0.4) #3894
Conversation
This adds the previously standalone security considerations document as a top-level section just before the appendices.
| @@ -3517,6 +3517,32 @@ Two examples of this: | |||
| 1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. | |||
| 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see. | |||
|
|
|||
| ## Security Considerations | |||
|
|
||
| ### Security Schemes | ||
|
|
||
| An OpenAPI document describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations. |
There was a problem hiding this comment.
Thank you for including this. I think this opens the door for some other proposals to officially signal that some of the less secure schemes will be deprecated in future versions of the API. (similar to what OpenAPI does today to deprecate resources).
There was a problem hiding this comment.
@miqui credit goes to @darrelmiller – he wrote this as a separate document (because we can't change the old specs) and I'm just putting it in the new versions of the spec :-)
| ### OpenAPI Document Formats | ||
|
|
||
| OpenAPI documents use JSON, YAML, and JSON Schema, and therefore share their security considerations: | ||
| - [JSON](https://www.iana.org/assignments/media-types/application/json) |
There was a problem hiding this comment.
| - [JSON](https://www.iana.org/assignments/media-types/application/json) | |
| - [JSON](https://www.rfc-editor.org/rfc/rfc8259.html#section-12) |
Why not directly reference the section on security considerations?
|
|
||
| OpenAPI documents use JSON, YAML, and JSON Schema, and therefore share their security considerations: | ||
| - [JSON](https://www.iana.org/assignments/media-types/application/json) | ||
| - [YAML](https://www.iana.org/assignments/media-types/application/yaml) |
There was a problem hiding this comment.
| - [YAML](https://www.iana.org/assignments/media-types/application/yaml) | |
| - [YAML](https://www.rfc-editor.org/rfc/rfc9512#name-security-considerations) |
| OpenAPI documents use JSON, YAML, and JSON Schema, and therefore share their security considerations: | ||
| - [JSON](https://www.iana.org/assignments/media-types/application/json) | ||
| - [YAML](https://www.iana.org/assignments/media-types/application/yaml) | ||
| - [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13) |
There was a problem hiding this comment.
| - [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13) | |
| - [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#name-security-considerations) |
|
@ralfhandl this PR is really just to incorporate the pre-approved text into the spec. There was already a PR for debating the text. I'm not comfortable changing this as I recall someone (maybe @ioggstream ?) requesting those specific URLs- you'll have to ask @darrelmiller |
Yep, #3619. Surprising. |
|
@ralfhandl the need for the security requirements comes from working on the media type registration IETF draft, which @ioggstream started (and, after discussion with @darrelmiller who co-chairs that working group, I'll be picking up in the near future). But @ioggstream knows what the requirements are here so I'd trust his choice of reference URIs. |
|
Yes. We should reference the IANA registry and not the RFC directly. Since media types can be changed outside RFCs, or RFCs can be obsoleted, the IANA process should guarantee that the Media type registration always references the latest information. |
|
Pity that the IANA registry breaks the hypermedia paradigm and only provides plain-text representations 😞 |
This adds the previously standalone security considerations document as a top-level section just before the appendices.