Merge pull request OAI#828 from OAI/dm/componentsreview

Components Review

Author: darrelmiller

versions/3.0.md

@@ -383,8 +383,9 @@ This object can be extended with [Specification Extensions](#specificationExtens
 
 #### <a name="componentsObject"></a>Components Object
 
-Holds a set of schemas for different aspects of the OAS.
-The intention is to put reusable components into a single ___location, allowing reuse from this and other OAS documents.
+Holds a set of reusable objects for different aspects of the OAS.
+All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
+
 
 ##### Fixed Fields
 
@@ -393,9 +394,13 @@ Field Pattern | Type | Description
 <a name="definitionsObject"></a> | [Definitions Object](#definitionsObject) | A hash containing payload definitions for the specification.
 <a name="responsesDefinitionsObject"></a> | [Responses Definitions Object](#responsesDefinitionsObject) | Reusable responses objects.
 <a name="parametersDefinitionsObject"></a> | [Parameters Definitions Object](#parametersDefinitionsObject) | An object to hold parameters to be reused across operations. Parameter definitions can be referenced to the ones defined here.
+<a name="requestBodyDefinitionsObject"></a> | [Request Body Definitions Object](#requestBodyDefinitionsObject) | An object to hold request body definitions to be reused across operations. Request Body definitions can be referenced to the ones defined here.
 <a name="responseHeadersDefinitionsObject"></a> | [Response Headers Definitions Object](#responseHeadersDefinitionsObject) | Response headers to reuse across the specification.
 <a name="securityDefinitionsObject"></a> | [Security Definitions Object](#securityDefinitionsObject) | Security definitions to reuse across the specification.
+<a name="linksDefinitionObject"></a> | [Link Definitions Object](#linksDefinitionsObject) | Link definitions to reuse across the specification.
+<a name="callbacksDefinitionObject"></a> | [Callback Definitions Object](#callbacksDefinitionsObject) | Callback definitions to reuse across the specification.
 
+All the fixed fields declared above are objects that MUST use keys that match the regular expression: `[a-zA-Z0-9.\-_]+`.
 
 #### <a name="pathsObject"></a>Paths Object
 
@@ -662,7 +667,7 @@ parameters:
   description: ID of pet that needs to be updated
   required: true
   type: string
-responseBody:
+requestBody:
   content:
     'application/x-www-form-urlencoded':
       schema:
@@ -2832,15 +2837,14 @@ animals:
 
 #### <a name="definitionsObject"></a>Definitions Object
 
-An object to hold data types that can be consumed and produced by operations.
+An object to hold schemas for data types that can be consumed and produced by operations.
 These data types can be primitives, arrays or models.
 
 ##### Patterned Fields
 
 Field Pattern | Type | Description
 ---|:---:|---
 <a name="definitionsName"></a>{name} | [Schema Object](#schemaObject) | A single definition, mapping a "name" to the schema it defines.
-The following characters are legal in the `definitionsName`: `a-zA-Z0-9.-_\`.  All other characters, including extended ASCII characters, are not legal in the `definitionsName`.  The name may be used to namespace the definitions--it is the tooling Specification's job to ensure that the namespace is honored.
 
 Examples: