From dc3380f33e0f8ded94f0b2a7b9fe063c6dc8ffeb Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Mon, 17 Feb 2025 10:41:49 -0500 Subject: [PATCH 1/5] Documented how OpenAPI references are used --- OpenAPI/OpenAPI.NET/references-openapi.md | 139 ++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 OpenAPI/OpenAPI.NET/references-openapi.md diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md new file mode 100644 index 0000000..7ff67d4 --- /dev/null +++ b/OpenAPI/OpenAPI.NET/references-openapi.md @@ -0,0 +1,139 @@ +--- +title: References in OpenAPI documents +description: Learn the types of references that are supportined in the OpenAPI.NET library. +author: darrmi +ms.author: darrmi +ms.topic: conceptual +--- + +# References in OpenAPI documents + +OpenAPI uses the keyword `$ref` to enable referencing and reusing existing objects defined in an OpenAPI description. However, there are many different ways to use this keyword and not all are supported by the OpenAPI.NET library. Also, OpenAPI 3.1 formalized the distinction between the use of the `$ref` keyword in a Schema object vs elsewhere in an OpenAPI description. To best understand how to use `$ref` it is helpful to be aware of its capabilities and the current limitations of OpenAPI.Net. + +## Reference Objects + +Prior to OpenAPI v3.1, Reference Objects was the term for all usages of `$ref` within OpenAPI descriptions. However, when OpenAPI v3.1 introduced support for JSON Schema beyond the draft-4 version, it became necessary to allow the use of `$ref` within Schema Objects to follow the rules of JSON Schema and all other uses in OpenAPI descriptions would be considered Reference Objects. Therefore, this section only describes the rules for `$ref` keywords that are not in a Schema Object. + +### Where Reference Objects can be used + +Reference objects can appear in one of two places. Either in place of an inline object, or a map value in the components section. + +This example below shows a common usage pattern of referencing a shared parameter object using a reference object. + +```yaml +openapi: 3.1.0 +info: + title: Example of reference object pointing to a parameter +paths: + /item: + get: + parameters: + $ref: '#/components/parameters/size' +components: + parameters: + size: + type: number +``` + +The following example shows a way to externalize security schemes using a reference object in a component. This is necessary because security requirement objects do not allow referencing using an external URI. + +```yaml +openapi: 3.1.0 +info: + title: Example of reference object in a component object +paths: + /item: + get: + security: + - customapikey: [] +components: + securitySchemes: + customapikey: + $ref: ./commonSecuritySchemes/customapikey.json#/components/securityschemes/customapikey +``` + + +### Targeting Mechanisms used in Reference objects + +Reference objects can use a relative reference with just a fragment identifier to point to an OAS Component. + +```yaml +openapi: 3.1.0 +info: + title: Example of reference object pointing to a parameter +paths: + /jobs/{id}: + $ref: '#/components/pathItems/job' +components: + pathItems: + job: + get: + patch: + delete: +``` + +Reference objects can reference OAS components in another OpenAPI document. + +```yaml +openapi: 3.1.0 +info: + title: Example of reference object pointing to an example object in an OpenAPI document +paths: + /items: + get: + responses: + 200: + description: Ok + application/json: + examples: + item-list: + $ref: './examples.yaml#/components/item-list' + +``` + +```yaml +# file for examples (examples.yaml) +openapi: 3.1.0 +info: + title: OpenAPI document containing examples for reuse +components: + examples: + item-list: + value: + - name: thing + description: a thing +``` + +For completeness, Reference Objects can also point to targets in a JSON/YAML document that contain properly formed OpenAPI objects, but not complete OpenApi document. We refer to these as OpenAPI "fragments". Currently OpenAPI.NET does not support referencing OpenAPI fragments. + +```yaml +openapi: 3.1.0 +info: + title: Example of reference object pointing to a parameter +paths: + /items: + get: + responses: + 200: + description: Ok + application/json: + examples: + item-list: + $ref: './examples.yaml#/item-list' + +``` + +```yaml +# file for example fragments (examples.yaml) +item-list: + value: + - name: thing + description: a thing +``` + + +### What types Reference objects can target + +Reference objects can be used to target the follow OAS types: parameter, response, example, header, securityScheme, link, callback and pathItem. In OpenAPI 3.0, they also can reference schema objects. + +## JSON Schema $refs in OpenAPI descriptions \ No newline at end of file From f313a605c7ebba7f8060293546e539963b57c21d Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Mon, 17 Feb 2025 13:18:03 -0500 Subject: [PATCH 2/5] Added the reference sources --- OpenAPI/OpenAPI.NET/references-openapi.md | 139 +++++++++++++++++++++- 1 file changed, 138 insertions(+), 1 deletion(-) diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md index 7ff67d4..59e78f5 100644 --- a/OpenAPI/OpenAPI.NET/references-openapi.md +++ b/OpenAPI/OpenAPI.NET/references-openapi.md @@ -24,6 +24,7 @@ This example below shows a common usage pattern of referencing a shared paramete openapi: 3.1.0 info: title: Example of reference object pointing to a parameter + version: 1.0.0 paths: /item: get: @@ -41,6 +42,7 @@ The following example shows a way to externalize security schemes using a refere openapi: 3.1.0 info: title: Example of reference object in a component object + version: 1.0.0 paths: /item: get: @@ -61,6 +63,7 @@ Reference objects can use a relative reference with just a fragment identifier t openapi: 3.1.0 info: title: Example of reference object pointing to a parameter + version: 1.0.0 paths: /jobs/{id}: $ref: '#/components/pathItems/job' @@ -78,6 +81,7 @@ Reference objects can reference OAS components in another OpenAPI document. openapi: 3.1.0 info: title: Example of reference object pointing to an example object in an OpenAPI document + version: 1.0.0 paths: /items: get: @@ -96,6 +100,7 @@ paths: openapi: 3.1.0 info: title: OpenAPI document containing examples for reuse + version: 1.0.0 components: examples: item-list: @@ -110,6 +115,7 @@ For completeness, Reference Objects can also point to targets in a JSON/YAML doc openapi: 3.1.0 info: title: Example of reference object pointing to a parameter + version: 1.0.0 paths: /items: get: @@ -136,4 +142,135 @@ item-list: Reference objects can be used to target the follow OAS types: parameter, response, example, header, securityScheme, link, callback and pathItem. In OpenAPI 3.0, they also can reference schema objects. -## JSON Schema $refs in OpenAPI descriptions \ No newline at end of file +## JSON Schema $refs in OpenAPI descriptions + +From OpenAPI 3.1 onwards, a `$ref` inside a Schema object is not considered an OpenAPI Reference Object. It behaves like a JSON Schema reference, specifically a JSON Schema 2020-12 reference, unless the dialect is changed for the OpenAPI document. + +### Where can JSON Schema references be used + +JSON Schema references can be used in the following locations: + +- at the root of an inline schema +- in a subschema of an inline schema +- at the root of a component schema +- in a subschema of a component schema + +#### Root of an inline schema + +```yaml +openapi: 3.1.0 +info: + title: Reference in at the root of an inline schema + version: 1.0.0 +paths: + /item: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: '#/components/schemas/item' +components: + schemas: + item: + type: object + +``` + +#### In a subschema of an inline schema + +```yaml +openapi: 3.1.0 +info: + title: Reference in at the root of an inline schema + version: 1.0.0 +paths: + /items: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/item' +components: + schemas: + item: + type: object +``` + +#### At the root of a component schema + +```yaml +openapi: 3.1.0 +info: + title: Reference at the root of a component schema + version: 1.0.0 +paths: + /items: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/specialitem' +components: + schemas: + specialitem: # Use the item type but provide a different title for the type + title: Special Item + $ref: "#/components/schemas/item" + item: + type: object +``` + +#### In a subschema of a component schema + +```yaml +openapi: 3.1.0 +info: + title: Reference in a subschema of an component schema + version: 1.0.0 +paths: + /items: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: '#/components/schemas/items' +components: + schemas: + items: + type: array + items: + $ref: '#/components/schemas/item' + item: + type: object +``` + + +### What kinds of JSON Schema references exist + +JSON Schema references can use either a locator or an identifier. Locators indicate where to find the target schema based on the name and structure of documents. However, identifiers are opaque URIs that match to the identifer of a JSON schema that has a $id either explicitly or implicitly by inheriting an identity from its parent. + +### What can a JSON Schema locator reference target + +- An internal component +- An interal component subschema +- An internal inline subschema [Not supported] +- An external OpenApi document component +- An external inline subchema [Not supported] +- An external fragment [Not supported] + +### What can a JSON Schema identifier reference target \ No newline at end of file From 69f97c4d08855011d5a570729c6b8a18dc42f131 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Mon, 17 Feb 2025 17:38:48 -0500 Subject: [PATCH 3/5] Added more reference examples --- OpenAPI/OpenAPI.NET/references-openapi.md | 306 +++++++++++++++++++++- 1 file changed, 305 insertions(+), 1 deletion(-) diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md index 59e78f5..448716b 100644 --- a/OpenAPI/OpenAPI.NET/references-openapi.md +++ b/OpenAPI/OpenAPI.NET/references-openapi.md @@ -271,6 +271,310 @@ JSON Schema references can use either a locator or an identifier. Locators indic - An internal inline subschema [Not supported] - An external OpenApi document component - An external inline subchema [Not supported] +- An external inline subchema using anchor - An external fragment [Not supported] -### What can a JSON Schema identifier reference target \ No newline at end of file +#### An internal component + +```yaml +openapi: 3.1.0 +info: + title: Reference to an internal component + version: 1.0.0 +paths: + /item: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: '#/components/schemas/item' +components: + schemas: + item: + type: object +``` + +#### An interal component subschema + +```yaml +openapi: 3.1.0 +info: + title: Reference to an internal component + version: 1.0.0 +paths: + /person/{id}: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: '#/components/schemas/person' + /person/{id}/address: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: '#/components/schemas/person/address' +components: + schemas: + person: + type: object + properties: + name: + type: string + address: + type: object + properties: + street: + type: string + city: + type: string +``` +#### An external OpenApi document component + +```yaml +openapi: 3.1.0 +info: + title: Reference to an external OpenApi document component + version: 1.0.0 +paths: + /person/{id}: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: 'OAS-schemas.yaml#/components/schemas/person' +``` + +```yaml +# OAS-schemas.yaml file +openapi: 3.1.0 +info: + title: OpenAPI document containing reusable components + version: 1.0.0 +components: + schemas: + person: + type: object + properties: + name: + type: string + address: + type: object + properties: + street: + type: string + city: + type: string +``` + + +#### An external inline subchema [Not supported and not recommended] + +```yaml +openapi: 3.1.0 +info: + title: Reference to an external OpenApi document component + version: 1.0.0 +paths: + /person/{id}: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: 'OAS-schemas.yaml#/components/schemas/person/properties/address' +``` + +```yaml +# OAS-schemas.yaml file +openapi: 3.1.0 +info: + title: OpenAPI document containing reusable components + version: 1.0.0 +components: + schemas: + person: + type: object + properties: + name: + type: string + address: + type: object + properties: + street: + type: string + city: + type: string + +``` + + +#### An external inline subchema using an anchor [Not currently supported] + +```yaml +openapi: 3.1.0 +info: + title: Reference to an external OpenApi document component + version: 1.0.0 +paths: + /person/{id}: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: 'OAS-schemas.yaml#address' +``` + +```yaml +# OAS-schemas.yaml file +openapi: 3.1.0 +info: + title: OpenAPI document containing reusable components + version: 1.0.0 +components: + schemas: + person: + type: object + properties: + name: + type: string + address: + $anchor: address + type: object + properties: + street: + type: string + city: + type: string + +``` + + +#### An external fragment [Not supported] + +```yaml +openapi: 3.1.0 +info: + title: Reference to an external OpenApi document component + version: 1.0.0 +paths: + /person/{id}: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: 'OAS-schemas.yaml#/person/properties/address' +``` + +```yaml +# OAS-schemas.yaml file +person: + type: object + properties: + name: + type: string + address: + type: object + properties: + street: + type: string + city: + type: string + +``` + + +### What can a JSON Schema identifier reference target + +- Reference an internal component using a $id +- Reference an internal subschema using a $id + +#### Reference an internal component using a $id +```yaml +openapi: 3.1.0 +info: + title: Reference an internal component using id + version: 1.0.0 +paths: + /person/{id}: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: 'https://schemas.acme.org/person' +components: + person: + $id: 'https://schemas.acme.org/person' + type: object + properties: + name: + type: string + address: + type: object + properties: + street: + type: string + city: + type: string +``` + +#### Reference an internal subschema using a $id +```yaml +openapi: 3.1.0 +info: + title: Reference an internal subschema using id + version: 1.0.0 +paths: + /person/{id}/address: + get: + responses: + 200: + description: ok + content: + application/json: + schema: + $ref: 'https://schemas.acme.org/address' +components: + person: + $id: 'https://schemas.acme.org/person' + type: object + properties: + name: + type: string + address: + $id: 'address' + type: object + properties: + street: + type: string + city: + type: string +``` + +#### Reference an external components and subschemas using a $id + +External components and subschemas are referenced in the exact same way as internal components. + From b89b424105c77e9f6a7b40038f69ae811b16f8b9 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Mon, 17 Feb 2025 17:42:11 -0500 Subject: [PATCH 4/5] Added new heading --- OpenAPI/OpenAPI.NET/references-openapi.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md index 448716b..97c5687 100644 --- a/OpenAPI/OpenAPI.NET/references-openapi.md +++ b/OpenAPI/OpenAPI.NET/references-openapi.md @@ -508,8 +508,9 @@ person: - Reference an internal component using a $id - Reference an internal subschema using a $id +- Reference external components and subschemas using a $id -#### Reference an internal component using a $id +#### Reference an internal component using a $id ```yaml openapi: 3.1.0 info: @@ -574,7 +575,7 @@ components: type: string ``` -#### Reference an external components and subschemas using a $id +#### Reference external components and subschemas using a $id External components and subschemas are referenced in the exact same way as internal components. From c2b8bfcee7340f62efbe9bb87b9b68c3d0278afb Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Sat, 19 Apr 2025 15:10:04 -0400 Subject: [PATCH 5/5] Many updates to the references examples --- OpenAPI/OpenAPI.NET/references-openapi.md | 122 ++++++++++++++++++---- 1 file changed, 103 insertions(+), 19 deletions(-) diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md index 97c5687..d972881 100644 --- a/OpenAPI/OpenAPI.NET/references-openapi.md +++ b/OpenAPI/OpenAPI.NET/references-openapi.md @@ -62,17 +62,19 @@ Reference objects can use a relative reference with just a fragment identifier t ```yaml openapi: 3.1.0 info: - title: Example of reference object pointing to a parameter + title: Example of reference object pointing to a pathitem version: 1.0.0 paths: /jobs/{id}: - $ref: '#/components/pathItems/job' + post: + requestBody: + $ref: '#/components/requestBodies/job' components: - pathItems: + requestBodies: job: - get: - patch: - delete: + required: true + content: + application/json: {} ``` Reference objects can reference OAS components in another OpenAPI document. @@ -91,8 +93,7 @@ paths: application/json: examples: item-list: - $ref: './examples.yaml#/components/item-list' - + $ref: './examples.yaml#/components/examples/item-list' ``` ```yaml @@ -109,7 +110,7 @@ components: description: a thing ``` -For completeness, Reference Objects can also point to targets in a JSON/YAML document that contain properly formed OpenAPI objects, but not complete OpenApi document. We refer to these as OpenAPI "fragments". Currently OpenAPI.NET does not support referencing OpenAPI fragments. +For completeness, Reference Objects can also point to targets in a JSON/YAML document that contain properly formed OpenAPI objects, but is not a complete OpenApi document. We refer to these as OpenAPI "fragments". Currently OpenAPI.NET does not support referencing OpenAPI fragments. ```yaml openapi: 3.1.0 @@ -132,15 +133,15 @@ paths: ```yaml # file for example fragments (examples.yaml) item-list: - value: - - name: thing - description: a thing + value: + - name: thing + description: a thing ``` ### What types Reference objects can target -Reference objects can be used to target the follow OAS types: parameter, response, example, header, securityScheme, link, callback and pathItem. In OpenAPI 3.0, they also can reference schema objects. +Reference objects can be used to target the follow OAS types: parameter, response, requestBody, example, header, securityScheme, link, callback and pathItem. In OpenAPI 3.0, they also can reference schema objects. ## JSON Schema $refs in OpenAPI descriptions @@ -229,6 +230,7 @@ components: title: Special Item $ref: "#/components/schemas/item" item: + title: Item type: object ``` @@ -259,6 +261,63 @@ components: type: object ``` +#### References local to a JSON Schema Resource defined by an OpenAPI Schema + +JSON Schema defines the concept of a JSON Schema Resource which is identified by a URI. $ref values can be specified relative to the JSON Schema Resource. Each OpenAPI schema object can be considered a JSON Schema Resource. + +In this example schema "a" is a JSON Schema resource and the reference in the "b" property of the "c" object is relative to the JSON Schema resource "a". Unfortunately, OpenAPI 3.1 has no well defined URIs for OpenAPI Schemas. This should be resolved in OpenAPI 3.2 with the introduction of a new top level "self" property. + +```yaml +components: +schema: + a: + type: + - object + - 'null' + properties: + b: + type: + - object + - 'null' + properties: + c: + type: + - object + - 'null' + properties: + b: + $ref: '#/properties/b' +``` + +#### References local to a JSON Schema Resource defined by a $id + +```yaml +components: +schema: + a: + type: + - object + - 'null' + additionalProperties: false + properties: + b: + type: + - object + - 'null' + additionalProperties: false + properties: + c: + $id: 'http://example.org/c' + type: + - object + - 'null' + additionalProperties: false + properties: + b: + $ref: '#/properties/d' + d: + type: string +``` ### What kinds of JSON Schema references exist @@ -268,7 +327,7 @@ JSON Schema references can use either a locator or an identifier. Locators indic - An internal component - An interal component subschema -- An internal inline subschema [Not supported] +- An internal inline subschema - An external OpenApi document component - An external inline subchema [Not supported] - An external inline subchema using anchor @@ -297,7 +356,7 @@ components: type: object ``` -#### An interal component subschema +#### An internal component subschema ```yaml openapi: 3.1.0 @@ -322,7 +381,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/person/address' + $ref: '#/components/schemas/person/properties/address' components: schemas: person: @@ -338,6 +397,8 @@ components: city: type: string ``` + + #### An external OpenApi document component ```yaml @@ -380,7 +441,7 @@ components: ``` -#### An external inline subchema [Not supported and not recommended] +#### An external inline subchema ```yaml openapi: 3.1.0 @@ -425,6 +486,8 @@ components: #### An external inline subchema using an anchor [Not currently supported] +We accept pull requests. + ```yaml openapi: 3.1.0 info: @@ -500,7 +563,6 @@ person: type: string city: type: string - ``` @@ -542,12 +604,14 @@ components: type: string ``` -#### Reference an internal subschema using a $id +#### Reference an internal subschema using a $id [Not supported yet] + ```yaml openapi: 3.1.0 info: title: Reference an internal subschema using id version: 1.0.0 + paths: /person/{id}/address: get: @@ -579,3 +643,23 @@ components: External components and subschemas are referenced in the exact same way as internal components. +## $ref in PathItem Objects + +This scenario is unsupported in OpenAPI.NET. + +```yaml +openapi: 3.1.0 +info: + title: Example of reference object pointing to a pathitem + version: 1.0.0 +paths: + /jobs/{id}: + get: + $ref: '#/components/pathItems/job' +components: + pathItems: + job: + get: + patch: + delete: +```