From 6c3fa9f4509644406b239bed5b362ef3fa2a8453 Mon Sep 17 00:00:00 2001 From: David Biesack Date: Tue, 4 Apr 2017 14:51:26 -0400 Subject: [PATCH 1/3] Update examplesObject Clarify that Examples Object may be used instead of Example Object. Show JSON examples as well as YAML Clarify the $ref values used in examples to remove ambiguity. These are not references to external JSON/XML/TXT resources, but rather are references to reusable examples in the current OpenAPI definition or in an external OpenAPI definition's components/examples This does not yet address issue #488 but cleans up Examples Object a bit, which is needed whether we alter the OAS as per #488 . --- versions/3.0.md | 148 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 122 insertions(+), 26 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index fd613139ee..f8d45aeb23 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1128,20 +1128,20 @@ A request body with a referenced model definition. "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/examples/user-example.json" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.json" ] }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/examples/user-example.xml" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.xml" ] }, "text/plain": { - "examples": [ "http://foo.bar/examples/user-example.txt" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.txt" ] }, "*/*": { "example": { - "$ref": "http://foo.bar/examples/user-example.whatever" + "$ref": "http://foo.bar/other-api.yaml#/components/examples/user-example.whatever" } } } @@ -1155,18 +1155,18 @@ content: schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/examples/user-example.json' + - 'http://foo.bar/other-api.yaml#/components/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/examples/user-example.xml' + - 'http://foo.bar/other-api.yaml#/components/examples/user-example.xml' 'text/plain': examples: - - 'http://foo.bar/examples/user-example.txt' + - 'http://foo.bar/other-api.yaml#/components/examples/user-example.txt' '*/*': example: - $ref: 'http://foo.bar/examples/user-example.whatever' + $ref: 'http://foo.bar/other-api.yaml#/components/examples/user-example.whatever' ``` A body parameter that is an array of string values: @@ -2355,7 +2355,12 @@ description: Pets operations #### Examples Object -Anywhere an `example` may be given, a JSON Reference MAY be used, with the +Instead of a single `example`, you may provide an array of +[Example Object](#exampleObject) values named `examples'. +`example` and `examples` are mutually exclusive. + +Anywhere an `example` may be given (including in the Examples Object array), +a JSON Reference MAY be used, with the explicit restriction that examples having a JSON format with object named `$ref` are not allowed. This does mean that `example`, structurally, can be either a string primitive or an object, similar to `additionalProperties`. @@ -2365,33 +2370,103 @@ for the value that it is accompanying. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are not compatible. +Here is a single `example` in a model [Schema Object](#schemaObject): + +```json + "components" : { + "schemas" : { + "identity" : { + "properties" : { + "name" : { + "type" : "string" + } + }, + "example" : { + "$ref" : "#/components/examples/identity" + } + } + } +``` +} + ```yaml -# in a model -schemas: - properties: - name: - type: string +components: + schemas: + identity: + properties: + name: + type: string example: - $ref: http://foo.bar#/examples/name-example + $ref: "#/components/examples/identity" +``` -# in a request body, note the plural `examples` as the Content-Type is set to `*`: +Below is an `examples` array in a [Request Body Object](#requestBodyObject), +showing two in-line examples and references +to examples in the document's [Components Object](#componentsObject): + +```json + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Address" + }, + "examples" : [ { + "street" : "119 N Weatherly Ave.", + "zip" : "55405" + }, { + "street" : "119 N Weatherly Ave", + "street2" : "Apt. D", + "city" : "Minneapolis", + "state" : "MN", + "zip" : "55405", + "type" : "residence" + }, { + "$ref" : "#/components/examples/alt-address" + } ] + }, + "application/xml" : { + "examples" : [ { + "$ref" : "#/components/examples/simple-address.xml" + }, { + "$ref" : "#/components/examples/complete-address.xml" + } ] + }, + "text/plain" : { + "examples" : [ { + "$ref" : "#/components/examples/address-example.txt" + } ] + } + } + } +``` + +```yaml requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: - - {"foo": "bar"} - - {"bar": "baz"} + - { "street": "119 N Weatherly Ave.", "zip" : "55405" } + - street: 119 N Weatherly Ave + street2: Apt. D + city: Minneapolis + state: MN + zip : '55405' + type: residence + - $ref: '#/components/examples/alt-address' 'application/xml': examples: - - $ref: 'http://foo.bar#/examples/address-example.xml' + - $ref: '#/components/examples/simple-address.xml' + - $ref: '#/components/examples/complete-address.xml' 'text/plain': examples: - - $ref: 'http://foo.bar#/examples/address-example.txt' - -# in a parameter - + - $ref: '#/components/examples/address-example.txt' +``` +This shows referencing an example component from another OpenAPI definition, +in a [Parameter Object](#parameterObject): +```yaml parameters: - name: 'zipCode' in: 'query' @@ -2399,8 +2474,29 @@ schemas: type: 'string' format: 'zip-code' example: - $ref: 'http://foo.bar#/examples/zip-example' -# in a response, note the plural `examples`: + $ref: 'http://foo.bar/other-api.yaml#/components/examples/zip-example' +``` + +Finally, in a [Response Object](#responseObject): + +```json + "responses" : { + "200" : { + "description" : "your car appointment has been booked", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/SuccessResponse" + }, + "example" : { + "$ref" : "http://foo.bar/other-api.yaml#/components/examples/address-example.json" + } + } + } + } +}``` + +```yaml responses: '200': description: your car appointment has been booked @@ -2409,7 +2505,7 @@ schemas: schema: $ref: '#/components/schemas/SuccessResponse' example: - $ref: http://foo.bar#/examples/address-example.json + $ref: http://foo.bar/other-api.yaml#/components/examples/address-example.json ``` #### Reference Object From a7b57fecdddb5baae015c5ff1ef56030518d24f1 Mon Sep 17 00:00:00 2001 From: David Biesack Date: Tue, 4 Apr 2017 17:42:05 -0400 Subject: [PATCH 2/3] Uniform synatx for $ref in examples Remove .json, .xml other extensions from examples so they do not look like file/resource names Use components/examples/camelCase not hyphenated-names uniformly --- versions/3.0.md | 58 ++++++++++++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index f8d45aeb23..5525edebdf 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -614,7 +614,7 @@ This object can be extended with [Specification Extensions](#specificationExtens "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/pet" + "$ref": "#/components/schemas/Pet" } } } @@ -638,7 +638,7 @@ This object can be extended with [Specification Extensions](#specificationExtens schema: type: array items: - $ref: '#/components/schemas/pet' + $ref: '#/components/schemas/Pet' ``` #### Path Item Object @@ -1128,20 +1128,20 @@ A request body with a referenced model definition. "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.json" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user" ] }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.xml" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/xmlUser" ] }, "text/plain": { - "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.txt" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/textUser" ] }, "*/*": { "example": { - "$ref": "http://foo.bar/other-api.yaml#/components/examples/user-example.whatever" + "$ref": "http://foo.bar/other-api.yaml#/components/examples/anyUser" } } } @@ -1155,18 +1155,18 @@ content: schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/other-api.yaml#/components/examples/user-example.json' + - 'http://foo.bar/other-api.yaml#/components/examples/user' 'application/xml': schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/other-api.yaml#/components/examples/user-example.xml' + - 'http://foo.bar/other-api.yaml#/components/xmlUser' 'text/plain': examples: - - 'http://foo.bar/other-api.yaml#/components/examples/user-example.txt' + - 'http://foo.bar/other-api.yaml#/components/examples/textUser' '*/*': example: - $ref: 'http://foo.bar/other-api.yaml#/components/examples/user-example.whatever' + $ref: 'http://foo.bar/other-api.yaml#/components/examples/anyUser' ``` A body parameter that is an array of string values: @@ -2386,8 +2386,8 @@ Here is a single `example` in a model [Schema Object](#schemaObject): } } } + } ``` -} ```yaml components: @@ -2422,19 +2422,19 @@ to examples in the document's [Components Object](#componentsObject): "zip" : "55405", "type" : "residence" }, { - "$ref" : "#/components/examples/alt-address" + "$ref" : "#/components/examples/altAddress" } ] }, "application/xml" : { "examples" : [ { - "$ref" : "#/components/examples/simple-address.xml" + "$ref" : "#/components/examples/simpleXmlAddress" }, { - "$ref" : "#/components/examples/complete-address.xml" + "$ref" : "#/components/examples/completeXmlAddress" } ] }, "text/plain" : { "examples" : [ { - "$ref" : "#/components/examples/address-example.txt" + "$ref" : "#/components/examples/textAddress" } ] } } @@ -2455,17 +2455,31 @@ to examples in the document's [Components Object](#componentsObject): state: MN zip : '55405' type: residence - - $ref: '#/components/examples/alt-address' + - $ref: '#/components/examples/altAddress' 'application/xml': examples: - - $ref: '#/components/examples/simple-address.xml' - - $ref: '#/components/examples/complete-address.xml' + - $ref: '#/components/examples/simpleXmlAddress' + - $ref: '#/components/examples/completeXmlAddress' 'text/plain': examples: - - $ref: '#/components/examples/address-example.txt' + - $ref: '#/components/examples/textAddress' ``` This shows referencing an example component from another OpenAPI definition, in a [Parameter Object](#parameterObject): + +```json + "parameters" : [ { + "name" : "zipCode", + "in" : "query", + "schema" : { + "type" : "string", + "format" : "zip-code", + "example" : { + "$ref" : "http://foo.bar/other-api.yaml#/components/examples/zipCode" + } + } + } ] +``` ```yaml parameters: - name: 'zipCode' @@ -2474,7 +2488,7 @@ in a [Parameter Object](#parameterObject): type: 'string' format: 'zip-code' example: - $ref: 'http://foo.bar/other-api.yaml#/components/examples/zip-example' + $ref: 'http://foo.bar/other-api.yaml#/components/examples/zipCode' ``` Finally, in a [Response Object](#responseObject): @@ -2489,7 +2503,7 @@ Finally, in a [Response Object](#responseObject): "$ref" : "#/components/schemas/SuccessResponse" }, "example" : { - "$ref" : "http://foo.bar/other-api.yaml#/components/examples/address-example.json" + "$ref" : "http://foo.bar/other-api.yaml#/components/examples/successResponse" } } } @@ -2505,7 +2519,7 @@ Finally, in a [Response Object](#responseObject): schema: $ref: '#/components/schemas/SuccessResponse' example: - $ref: http://foo.bar/other-api.yaml#/components/examples/address-example.json + $ref: http://foo.bar/other-api.yaml#/components/examples/successResponse ``` #### Reference Object From 1975b537e5667f63a5a4f0b6cdd4d9e32510a64f Mon Sep 17 00:00:00 2001 From: David Biesack Date: Tue, 4 Apr 2017 17:42:05 -0400 Subject: [PATCH 3/3] Uniform synatx for $ref in examples Remove .json, .xml other extensions from examples so they do not look like file/resource names Use components/examples/camelCase not hyphenated-names uniformly Move key descriptions (for $ref, schema constraints) and Example Object Example from Examples Object into Example Object. Include some examples that are just string values (ZipCode), an object (Address), and XML (SimpleXmlAddress) Improve examples for Example Object, show definitions in components/examples. Remove overly verbose examples from Examples Object --- versions/3.0.md | 361 ++++++++++++++++++++++++------------------------ 1 file changed, 184 insertions(+), 177 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index f8d45aeb23..f679ba6792 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -53,12 +53,12 @@ Additional utilities can also take advantage of the resulting files, such as tes - [Callback Object](#callbackObject) - [Headers Object](#headersObject) - [Example Object](#exampleObject) + - [Examples Array](#examplesArray) - [Links Object](#linksObject) - [Link Object](#linkObject) - [Link Parameters Object](#linkParametersObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - - [Examples Object](#examplesObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [XML Object](#xmlObject) @@ -614,7 +614,7 @@ This object can be extended with [Specification Extensions](#specificationExtens "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/pet" + "$ref": "#/components/schemas/Pet" } } } @@ -638,7 +638,7 @@ This object can be extended with [Specification Extensions](#specificationExtens schema: type: array items: - $ref: '#/components/schemas/pet' + $ref: '#/components/schemas/Pet' ``` #### Path Item Object @@ -1128,20 +1128,20 @@ A request body with a referenced model definition. "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.json" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user" ] }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, - "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.xml" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/xmlUser" ] }, "text/plain": { - "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.txt" ] + "examples": [ "http://foo.bar/other-api.yaml#/components/examples/textUser" ] }, "*/*": { "example": { - "$ref": "http://foo.bar/other-api.yaml#/components/examples/user-example.whatever" + "$ref": "http://foo.bar/other-api.yaml#/components/examples/anyUser" } } } @@ -1155,18 +1155,18 @@ content: schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/other-api.yaml#/components/examples/user-example.json' + - 'http://foo.bar/other-api.yaml#/components/examples/user' 'application/xml': schema: $ref: '#/components/schemas/User' examples: - - 'http://foo.bar/other-api.yaml#/components/examples/user-example.xml' + - 'http://foo.bar/other-api.yaml#/components/xmlUser' 'text/plain': examples: - - 'http://foo.bar/other-api.yaml#/components/examples/user-example.txt' + - 'http://foo.bar/other-api.yaml#/components/examples/textUser' '*/*': example: - $ref: 'http://foo.bar/other-api.yaml#/components/examples/user-example.whatever' + $ref: 'http://foo.bar/other-api.yaml#/components/examples/anyUser' ``` A body parameter that is an array of string values: @@ -1822,24 +1822,34 @@ X-Rate-Limit-Reset: #### Example Object -Allows sharing examples for operation requests and responses. This object can either be a freeform object, array or primitive value. To represent examples of media types that cannot naturally represented in the OpenAPI definition, a string value can be used to contain the example with escaping where necessary. +Allows sharing examples for operation requests and responses and other content. This object can either be a freeform object, array, or primitive value. +To represent examples of media types that cannot naturally represented in the OpenAPI definition, a string value can be used to contain the example with escaping where necessary. -##### Example Example +Anywhere an `example` may be given (including in and [Examples Array](#examplesArray)), +a [Reference Object](#referenceObject) MAY be used, with the +explicit restriction that examples having a JSON format with an object named +`$ref` are *not* allowed. -Example representation for application/json media type of a Pet data type: +The value SHOULD be compatible with the type schema +for the content that it is accompanying. Tooling implementations MAY choose to +validate compatibility automatically, and reject the example value(s) if they +are not compatible. + +##### Example Object Example + +Example representation for `application/json` media type of a Pet data type: ```json - { - "name": "Puma", - "type": "Dog", - "color": "Black", - "gender": "Female", - "breed": "Mixed" - } +{ + "name": "Puma", + "type": "Dog", + "color": "Black", + "gender": "Female", + "breed": "Mixed" +} ``` ```yaml - name: Puma type: Dog color: Black @@ -1848,6 +1858,158 @@ breed: Mixed ``` +A [Parameter Object](#parameterObject) referencing an example component from another OpenAPI definition: + +```json + "parameters" : [ { + "name" : "zipCode", + "in" : "query", + "schema" : { + "type" : "string", + "format" : "zip-code", + "example" : { + "$ref" : "http://foo.bar/other-api.yaml#/components/examples/ZipCode" + } + } + } ] +``` +```yaml + parameters: + - name: 'zipCode' + in: 'query' + schema: + type: 'string' + format: 'zip-code' + example: + $ref: 'http://foo.bar/other-api.yaml#/components/examples/ZipCode' +``` + +Several examples defined in the [Component Object](#Component Object) `examples` object: + +```json + "components" : { + "examples" : { + "ZipCode" : "12345", + "Address" : { + "street" : "119 N Weatherly Ave", + "street2" : "Apt. D", + "city" : "Minneapolis", + "state" : "MN", + "zip" : "55405", + "type" : "residence" + }, + "TextAddress" : "119 N Weatherly Ave, Apt. D, Minneapolis. MN 55405", + "SimpleXmlAddress" : "
119 N Weatherly Ave55405
" + } + } +``` + +```yaml +components: + examples: + ZipCode: '12345' + Address: + street: 119 N Weatherly Ave + street2: Apt. D + city: Minneapolis + state: MN + zip : '55405' + type: residence + TextAddress: "119 N Weatherly Ave, Apt. D, Minneapolis. MN 55405" + SimpleXmlAddress: + "
119 N Weatherly Ave55405
" +``` + +#### Examples Array + +Instead of a single `example`, you may provide an array of +[Example Object](#exampleObject) values named `examples`. +`example` and `examples` are mutually exclusive. + +##### Examples Array Examples + +Use of `examples` in a model [Schema Object](#schemaObject): + +```json + "components" : { + "schemas" : { + "address" : { + "properties" : { + "name" : { + "type" : "string" + } + }, + "examples" : [ { + "$ref" : "#/components/examples/Identity" + }, { + "$ref" : "#/components/examples/Identity2" + } ] + } + } + } +``` + +```yaml +components: + schemas: + Address: + examples: + - $ref: "#/components/examples/Identity" + - $ref: "#/components/examples/Identity2" +``` + +Below is an `examples` array in a [Request Body Object](#requestBodyObject), +showing two inline examples and references +to examples in the document's [Components Object](#componentsObject): + +```json + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Address" + }, + "examples" : [ { + "street" : "119 N Weatherly Ave.", + "zip" : "55405" + }, { + "$ref" : "#/components/examples/Address" + } ] + }, + "application/xml" : { + "examples" : [ { + "$ref" : "#/components/examples/SimpleXmlAddress" + }, { + "$ref" : "#/components/examples/CompleteXmlAddress" + } ] + }, + "text/plain" : { + "examples" : [ { + "$ref" : "#/components/examples/TextAddress" + } ] + } + } + } +``` + +```yaml + requestBody: + content: + 'application/json': + schema: + $ref: '#/components/schemas/Address' + examples: + - { "street": "119 N Weatherly Ave.", "zip" : "55405" } + - $ref: '#/components/examples/Address' + 'application/xml': + examples: + - $ref: '#/components/examples/SimpleXmlAddress' + - $ref: '#/components/examples/CompleteXmlAddress' + 'text/plain': + examples: + - $ref: '#/components/examples/TextAddress' +``` + #### Links Object The links object represents a set of possible design-time links for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. @@ -2353,161 +2515,6 @@ name: pet description: Pets operations ``` -#### Examples Object - -Instead of a single `example`, you may provide an array of -[Example Object](#exampleObject) values named `examples'. -`example` and `examples` are mutually exclusive. - -Anywhere an `example` may be given (including in the Examples Object array), -a JSON Reference MAY be used, with the -explicit restriction that examples having a JSON format with object named -`$ref` are not allowed. This does mean that `example`, structurally, can be -either a string primitive or an object, similar to `additionalProperties`. - -In all cases, the payload is expected to be compatible with the type schema -for the value that it is accompanying. Tooling implementations MAY choose to -validate compatibility automatically, and reject the example value(s) if they -are not compatible. - -Here is a single `example` in a model [Schema Object](#schemaObject): - -```json - "components" : { - "schemas" : { - "identity" : { - "properties" : { - "name" : { - "type" : "string" - } - }, - "example" : { - "$ref" : "#/components/examples/identity" - } - } - } -``` -} - -```yaml -components: - schemas: - identity: - properties: - name: - type: string - example: - $ref: "#/components/examples/identity" -``` - -Below is an `examples` array in a [Request Body Object](#requestBodyObject), -showing two in-line examples and references -to examples in the document's [Components Object](#componentsObject): - -```json - "requestBody" : { - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Address" - }, - "examples" : [ { - "street" : "119 N Weatherly Ave.", - "zip" : "55405" - }, { - "street" : "119 N Weatherly Ave", - "street2" : "Apt. D", - "city" : "Minneapolis", - "state" : "MN", - "zip" : "55405", - "type" : "residence" - }, { - "$ref" : "#/components/examples/alt-address" - } ] - }, - "application/xml" : { - "examples" : [ { - "$ref" : "#/components/examples/simple-address.xml" - }, { - "$ref" : "#/components/examples/complete-address.xml" - } ] - }, - "text/plain" : { - "examples" : [ { - "$ref" : "#/components/examples/address-example.txt" - } ] - } - } - } -``` - -```yaml - requestBody: - content: - 'application/json': - schema: - $ref: '#/components/schemas/Address' - examples: - - { "street": "119 N Weatherly Ave.", "zip" : "55405" } - - street: 119 N Weatherly Ave - street2: Apt. D - city: Minneapolis - state: MN - zip : '55405' - type: residence - - $ref: '#/components/examples/alt-address' - 'application/xml': - examples: - - $ref: '#/components/examples/simple-address.xml' - - $ref: '#/components/examples/complete-address.xml' - 'text/plain': - examples: - - $ref: '#/components/examples/address-example.txt' -``` -This shows referencing an example component from another OpenAPI definition, -in a [Parameter Object](#parameterObject): -```yaml - parameters: - - name: 'zipCode' - in: 'query' - schema: - type: 'string' - format: 'zip-code' - example: - $ref: 'http://foo.bar/other-api.yaml#/components/examples/zip-example' -``` - -Finally, in a [Response Object](#responseObject): - -```json - "responses" : { - "200" : { - "description" : "your car appointment has been booked", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/SuccessResponse" - }, - "example" : { - "$ref" : "http://foo.bar/other-api.yaml#/components/examples/address-example.json" - } - } - } - } -}``` - -```yaml - responses: - '200': - description: your car appointment has been booked - content: - application/json: - schema: - $ref: '#/components/schemas/SuccessResponse' - example: - $ref: http://foo.bar/other-api.yaml#/components/examples/address-example.json -``` - #### Reference Object A simple object to allow referencing other components in the specification, internally and externally.