|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Remove References |
| 4 | +nav_order: 3 |
| 5 | +parent: Using References |
| 6 | +--- |
| 7 | + |
| 8 | +# Remove References |
| 9 | + |
| 10 | +Sometimes it is useful to remove references in an OpenAPI Description (OAD). A common use case is working with tools that don't understand references well. This isn't always straightforward, however, and this page covers the main points to look out for. |
| 11 | + |
| 12 | +## Convert an OAD to a single-document form without any references |
| 13 | + |
| 14 | +Not all OADs can be converted but there are many cases where it is possible to do such a thing without problems. |
| 15 | + |
| 16 | +The difficult cases are: |
| 17 | + |
| 18 | +* Cyclic references in JSON Schema ***cannot*** be removed, although if the references cross documents, it is possible to reduce them to same-document references in a single document |
| 19 | +* While [dynamic references](dynamic) in OAS 3.1 Schema Objects technically can be converted to static references, it can [grow the schema size exponentially](https://dl.acm.org/doi/10.1145/3632891) ([pdf](https://dl.acm.org/doi/pdf/10.1145/3632891)) |
| 20 | +* OAS 3.1 Schema Objects, OAS 3.0 Reference Objects, and both OAS 3.0 and 3.1 Path Item Objects all allow keywords alongside a`"$ref"`, each with slightly different semantics; generic reference removal tools, particularly ones that predate OAS 3.1, may fail to preserve the behavior while removing references |
| 21 | +* In OAS 3.1 Schema Objects that use `"$id"`, reference removal tools that are not aware of `"$id"` will resolve references impacted by the `"$id"` incorrectly |
| 22 | +* The Link Object's `"operationRef"` cannot be replaced with an inline Operation Object (although if the target Operation Object has a unique-within-the-OAD `"operationId"`, then the `"operationRef"` can be replaced by the `"operationId"`) |
| 23 | +* The Discriminator Object's `"mapping"` field forbids inline Schema Objects; URI-reference values can be replaced with names from the `"schemas"` section of the Components Object, but when the Discriminator Object is in a referenced document, there are ambiguities involved in how to resolve those names |
| 24 | +* When using components published by 3rd parties such as standards organizations, tools might rely on reference URIs to identify standard components; while this usage is currently uncommon, it may become more common as OpenAPI is more broadly adopted by standards bodies |
| 25 | + |
| 26 | +If your OAD does not run afoul of any of the above difficulties, you _can_ produce a reference-less single-document OAD, and there are [tools](https://tools.openapis.org) that will do so (but see the caveats in the next section). |
| 27 | + |
| 28 | +## Convert a multi-document OAD into a single document |
| 29 | + |
| 30 | +It is possible to convert a multi-document OAD into a single document event if not all references can be removed. However, depending on exactly how your multi-document OAD is structured, this may be more complex than just removing references. Sadly, the reasons have to do with [painfully obscure and technical ambiguities](https://github.com/OAI/oascomply/blob/main/reports/processing-model-summary.md) regarding how multi-document OADs are intended to be parsed. The OpenAPI Initiative hopes to clarify this in future versions of the specification. |
| 31 | + |
| 32 | +* It is possible for a Link Object's `"operationId"` to point to an Operation Object in a Path Item Object that is never referenced; it is unclear how this case should handle it, which is one reason the OAS itself [advises against](https://spec.openapis.org/oas/v3.1.0#fixed-fields-16) using `"operationId"` in multi-document OADs |
| 33 | +* Security Scheme Objects are never referenced, only named in Security Requirement Objects, and must be taken into account |
| 34 | +* There is no standard place to put referenced Path Item Objects in OAS 3.0 |
| 35 | +* The resolution of server configuration and security settings can be unclear in multi-document OADs |
| 36 | + |
| 37 | +Again, in many cases none of this is a problem, and there are [tools](https://tools.openapis.org) that will do what you want. |
| 38 | + |
0 commit comments