diff --git a/guidelines/JSON_References.md b/guidelines/JSON_References.md new file mode 100644 index 0000000000..e66fd009fc --- /dev/null +++ b/guidelines/JSON_References.md @@ -0,0 +1,130 @@ +# Guidelines for Referencing + +The OpenAPI Specification relies on JSON Refereneces as the machinsm for reusability (DRY). This guide gives you a brief introduction to JSON References and its capability. It does not provide the full details which are covered in its own specification, but aims to provide you with information about the reference types. + +All references should follow the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification. + +JSON Reference provides guidance on the resolution of references, notably: + +> If the URI contained in the JSON Reference value is a relative URI, +then the base URI resolution MUST be calculated according to +[RFC3986], section 5.2. Resolution is performed relative to the +referring document. + +Whether you reference definitions locally or remote, you can never override or change their definitions from the referring location. The definitions can only be used as-is. + +### Local references + +When referencing locally (within the current document), the target references should follow the conventions, as defined by the spec: + +* Parameters -> `#/parameters` +* Responses -> `#/responses` +* Definitions (Models/Schema) -> `#/definitions` + +An example of a local definition reference: + +_Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json_ +``` json + // ... + "200": { + "description": "pet response", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/Pet" + } + } +``` + +### Remote references + +#### Relative path + +Files can be referred to in relative paths to the current document. + +_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ + +``` json +// ... +"responses": { + "default": { + "description": "unexpected error", + "schema": { + "$ref": "../common/Error.json" + } + } +} +``` + +Remote references may also reference properties within the relative remote file. + +_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ +``` json +// ... +"parameters": [ + { + "$ref": "parameters.json#/tagsParam" + }, + { + "$ref": "parameters.json#/limitsParam" + } +] +``` + + +#### URL + +Remote files can be hosted on an HTTP server (rather than the local file system). + +One risk of this approach is that environment specific issues could arise if DNS is not taken into account (as the reference can only contain one hostname). + +_Assuming file https://my.company.com/definitions/Model.json_ +```json +{ + "description": "A simple model", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "tag": { + "description": "A complex, shared property. Note the absolute reference", + "$ref": "https://my.company.com/definitions/Tag.json" + } + } +} +``` + +Remote references may also reference properties within the remote file. + +_Assuming file https://my.company.com/definitions/models.json_ +```json +{ + "models": { + "Model": { + "description": "A simple model", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "tag": { + "description": "a complex, shared property. Note the absolute reference", + "$ref": "https://my.company.com/definitions/models.json#/models/Tag" + } + } + }, + "Tag": { + "description": "A tag entity in the system", + "type": "object", + "properties": { + "name": { + "type": "string" + } + } + } + } +} +``` \ No newline at end of file diff --git a/guidelines/REUSE.md b/guidelines/REUSE.md index 2d3192c262..4f60cdb343 100644 --- a/guidelines/REUSE.md +++ b/guidelines/REUSE.md @@ -6,9 +6,9 @@ We encourage reuse and patterns through references. The following types are reusable, as defined by the spec: -* Parameters -* Models (_or Schema Objects in general_) +* Definitions (_Models or Schema Objects in general_) * Responses +* Parameters * Operations (_Operations can only be remote references_) ## Reuse strategy @@ -56,130 +56,66 @@ definitions: Note: YAML has a very similar feature, [YAML anchors](http://yaml.org/spec/1.2/spec.html#id2765878). Examples from this point will only be in JSON, using JSON References. -## Techniques - -### Guidelines for Referencing - -All references should follow the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification. - -JSON Reference provides guidance on the resolution of references, notably: - -> If the URI contained in the JSON Reference value is a relative URI, -then the base URI resolution MUST be calculated according to -[RFC3986], section 5.2. Resolution is performed relative to the -referring document. - -Whether you reference definitions locally or remote, you can never override or change their definitions from the referring location. The definitions can only be used as-is. - -#### Local references - -When referencing locally (within the current document), the target references should follow the conventions, as defined by the spec: - -* Parameters -> `#/parameters` -* Responses -> `#/responses` -* Definitions (Models/Schema) -> `#/definitions` - -An example of a local definition reference: - -_Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json_ -``` json - // ... - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } -``` - -#### Remote references - -##### Relative path +Please refer to the [JSON References Guidelines](JSON_References.md) for further details. -Files can be referred to in relative paths to the current document. +## Reusable Components -_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ -``` json -// ... -"responses": { - "default": { - "description": "unexpected error", - "schema": { - "$ref": "../common/Error.json" - } - } -} -``` +### Definitions -Remote references may also reference properties within the relative remote file. - -_Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ -``` json -// ... -"parameters": [ - { - "$ref": "parameters.json#/tagsParam" - }, - { - "$ref": "parameters.json#/limitsParam" - } -] -``` +Reuse schema definitions by creating a repository of definitions. This is done by simply hosting a file or set of files for commonly used definitions across a company or organization. +Refer to [Guidelines for Referencing](JSON_References.md) for referencing strategies. -##### URL +### Responses -Remote files can be hosted on an HTTP server (rather than the local file system). +Refer to [Guidelines for Referencing](JSON_References.md) for referencing strategies. -One risk of this approach is that environment specific issues could arise if DNS is not taken into account (as the reference can only contain one hostname). +Assume the file `responses.json`: -_Assuming file https://my.company.com/definitions/Model.json_ ```json { - "description": "A simple model", - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "tag": { - "description": "A complex, shared property. Note the absolute reference", - "$ref": "https://my.company.com/definitions/Tag.json" + "NotFoundError": { + "description": "Entity not found", + "schema": { + "$ref": "#/definitions/ErrorModel" } } } ``` -Remote references may also reference properties within the remote file. - -_Assuming file https://my.company.com/definitions/models.json_ +You can refer to it from a response definition: ```json { - "models": { - "Model": { - "description": "A simple model", - "type": "object", - "properties": { - "id": { + "/pets/{petId}": { + "get": { + "tags": [ + "pet" + ], + "summary": "Returns server health information", + "operationId": "getHealth", + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "petId", + "in": "path", + "description": "ID of pet to return", + "required": true, "type": "integer", "format": "int64" - }, - "tag": { - "description": "a complex, shared property. Note the absolute reference", - "$ref": "https://my.company.com/definitions/models.json#/models/Tag" } - } - }, - "Tag": { - "description": "A tag entity in the system", - "type": "object", - "properties": { - "name": { - "type": "string" + ], + "responses": { + "200": { + "description": "The pet", + "schema": { + "$ref": "#/definitions/Pet" + } + }, + "400": { + "$ref": "http://localhost:8000/responses.json#/NotFoundError" } } } @@ -187,19 +123,11 @@ _Assuming file https://my.company.com/definitions/models.json_ } ``` - -### Definitions - -Reuse schema definitions by creating a repository of definitions. This is done by simply hosting a file or set of files for commonly used definitions across a company or organization. - -Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. - - ### Parameters Similar to model schemas, you can create a repository of `parameters` to describe the common entities that appear throughout a set of systems. -Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. +Refer to [Guidelines for Referencing](#JSON_References.md) for referencing strategies. Using the same technique as above, you can host on either a single or multiple files. For simplicity, the example below assumes a single file. @@ -275,7 +203,7 @@ To include these parameters, you would need to add them individually as such: Again, Operations can be shared across files. Although the reusability of operations will be less than with Parameters and Definitions. For this example, we will share a common `health` resource so that all APIs can reference it: -Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. +Refer to [Guidelines for Referencing](JSON_References.md) for referencing strategies. ```json { @@ -314,59 +242,3 @@ Which points to the reference in the `operations.json` file: ``` Remember, you cannot override the definitions, but in this case, you can add additional operations on the same path level. - -### Responses - -Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. - -Assume the file `responses.json`: - -```json -{ - "NotFoundError": { - "description": "Entity not found", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } -} -``` - -You can refer to it from a response definition: -```json -{ - "/pets/{petId}": { - "get": { - "tags": [ - "pet" - ], - "summary": "Returns server health information", - "operationId": "getHealth", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet to return", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "200": { - "description": "The pet", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "400": { - "$ref": "http://localhost:8000/responses.json#/NotFoundError" - } - } - } - } -} -```