Adding modules

versions/4.0.0.md

@@ -17,6 +17,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 
 - [Definitions](#definitions)
 	- [OpenAPI Document](#oasDocument)
+	- [OpenAPI Module Document](#oasModule)
 	- [Path Templating](#pathTemplating)
 	- [Media Types](#mediaTypes)
 	- [HTTP Status Codes](#httpCodes)
@@ -60,6 +61,11 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 		- [Security Requirement Object](#securityRequirementObject)
 	- [Specification Extensions](#specificationExtensions)
 	- [Security Filtering](#securityFiltering)
+- [OAS Module Document Specification](#module)
+    - [Versions](#moduleVersions)
+    - [OAS Module Document Type](#moduleDocumentType)
+    - [Schema](#moduleSchema)
+        - [OpenAPI Module Object](#moduleObject)
 - [Appendix A: Revision History](#revisionHistory)
 
 
@@ -70,6 +76,9 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 ##### <a name="oasDocument"></a>OpenAPI Document
 A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
 
+##### <a name="oasModule"></a>OpenAPI Module Document
+A document defines or describes multiple reusable OpenAPI components that can be referenced from multiple OpenAPI documents.
+
 ##### <a name="pathTemplating"></a>Path Templating
 Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
 
@@ -3364,6 +3373,77 @@ 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 than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
 
+## <a name="module"></a> OAS Module Document Specification
+
+### <a name="moduleVersions"></a>Versions
+
+OAS Module documents, in the same way as the standard OAS documents, are versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.
+
+The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.
+
+Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version.  Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
+
+An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.)
+
+
+### <a name="moduleDocumentType"></a>OAS Module Document Type
+
+OAS Module documents are identified using the required field ['openapi-document'](#oasDocumentType) with a value that must match the string `"OAS Module"`.
+
+### <a name="moduleSchema"></a>Schema
+
+In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.
+
+#### <a name="fragmentObject"></a>OpenAPI Module Object
+
+This is the root document object for a [OpenAPI Module Object](#moduleObject)
+
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+<a name="moduleVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string
+<a name="oasDocumentType"></a>openapi-document | `string` | **REQUIRED**. This string MUST be the [`OAS Module`] value identifying the overlay document
+<a name="oasModuleDescription"></a>description | string | Description of the module usage
+<a name="Components"></a>components | [Module Components Object](#componentsObject) | An element to hold the schema for the module components
+
+##### OpenAPI Module Object Example
+
+A module describing several components can be described like this:
+
+``` yaml
+openapi: 4.0.0
+openapi-document: OAS Module
+description: Module with some shared components
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        name:
+          type: string
+        age:
+          type: number
+          format: int32
+    Account:
+      type: object
+      properties:
+        code:
+          type: string
+        balance:
+          type: number
+  parameters:
+    freeTextSearch:
+      name: search
+      in: query
+      description: free text search value
+      required: false
+      schema:
+        type: string
+
+```
+
 ## <a name="revisionHistory"></a>Appendix A: Revision History
 
 Version   | Date       | Notes