Updated Header Object, Removed Items Object
MODIFY
versions/3.0.md
versions/3.0.md
@@ -43,7 +43,6 @@ Additional utilities can also take advantage of the resulting files, such as tes
- [Request Body Object](#request-body-object)
- [Content Object](#content-object)
- [Content Type Object](#content-type-object)
- - [Items Object](#items-object)
- [Responses Object](#responses-object)
- [Response Object](#response-object)
- [Headers Object](#headers-object)
@@ -1282,71 +1281,6 @@ encoding:
contentType: image/png, image/jpeg
```
-#### <a name="itemsObject"></a>Items Object
-
-A limited subset of JSON-Schema's items object.
-It is used by parameter definitions.
-
-##### Fixed Fields
-Field Name | Type | Description
----|:---:|---
-<a name="itemsType"></a>type | `string` | **Required.** The internal type of the array. The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, or `"array"`. Files and models are not allowed.
-<a name="itemsFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details.
-<a name="itemsItems"></a>items | [Items Object](#itemsObject) | **Required if [`type`](#itemsType) is "array".** Describes the type of items in the array.
-<a name="itemsCollectionFormat"></a>collectionFormat | `string` | Determines the format of the array if type array is used. Possible values are: <ul><li>`csv` - comma separated values `foo,bar`. <li>`ssv` - space separated values `foo bar`. <li>`tsv` - tab separated values `foo\tbar`. <li>`pipes` - pipe separated values <code>foo&#124;bar</code>. </ul> Default value is `csv`.
-<a name="itemsDefault"></a>default | * | Declares the value of the item that the server will use if none is provided. (Note: "default" has no meaning for required items.) See http://json-schema.org/latest/json-schema-validation.html#anchor101. Unlike JSON Schema this value MUST conform to the defined [`type`](#itemsType) for the data type.
-<a name="itemsMaximum"></a>maximum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
-<a name="itemsMaximum"></a>exclusiveMaximum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
-<a name="itemsMinimum"></a>minimum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
-<a name="itemsExclusiveMinimum"></a>exclusiveMinimum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
-<a name="itemsMaxLength"></a>maxLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor26.
-<a name="itemsMinLength"></a>minLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor29.
-<a name="itemsPattern"></a>pattern | `string` | See http://json-schema.org/latest/json-schema-validation.html#anchor33.
-<a name="itemsMaxItems"></a>maxItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor42.
-<a name="itemsMinItems"></a>minItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor45.
-<a name="itemsUniqueItems"></a>uniqueItems | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor49.
-<a name="itemsEnum"></a>enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76.
-<a name="itemsMultipleOf"></a>multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14.
-
-This object can be extended with [Specification Extensions](#specificationExtensions).
-
-##### Items Object Examples
-
-Items must be of type string and have the minimum length of 2 characters:
-
-```json
-{
- "type": "string",
- "minLength": 2
-}
-```
-
-```yaml
-type: string
-minLength: 2
-```
-
-An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive):
-
-```json
-{
- "type": "array",
- "items": {
- "type": "integer",
- "minimum": 0,
- "maximum": 63
- }
-}
-```
-
-```yaml
-type: array
-items:
- type: integer
- minimum: 0
- maximum: 63
-```
-
#### <a name="responsesObject"></a>Responses Object
A container for the expected responses of an operation.
@@ -1606,28 +1540,37 @@ Rate-limit headers:
{
"X-Rate-Limit-Limit": {
"description": "The number of allowed requests in the current period",
+ "schema": {
"type": "integer"
+ }
},
"X-Rate-Limit-Remaining": {
"description": "The number of remaining requests in the current period",
+ "schema": {
"type": "integer"
+ }
},
"X-Rate-Limit-Reset": {
"description": "The number of seconds left in the current period",
+ "schema": {
"type": "integer"
}
}
+}
```
```yaml
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
+ schema:
type: integer
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
+ schema:
type: integer
X-Rate-Limit-Reset:
description: The number of seconds left in the current period
+ schema:
type: integer
```
@@ -2084,28 +2027,12 @@ In the above, the link for `UserCommitHistory` points to the operation `getUserC
#### <a name="headerObject"></a>Header Object
-Field Name | Type | Description
----|:---:|---
-<a name="headerDescription"></a>description | `string` | A short description of the header.
-<a name="headerType"></a>type | `string` | **Required.** The type of the object. The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, or `"array"`.
-<a name="headerFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#stType). See [Data Type Formats](#dataTypeFormat) for further details.
-<a name="headerItems"></a>items | [Items Object](#itemsObject) | **Required if [`type`](#stType) is "array".** Describes the type of items in the array.
-<a name="headerCollectionFormat"></a>collectionFormat | `string` | Determines the format of the array if type array is used. Possible values are: <ul><li>`csv` - comma separated values `foo,bar`. <li>`ssv` - space separated values `foo bar`. <li>`tsv` - tab separated values `foo\tbar`. <li>`pipes` - pipe separated values <code>foo&#124;bar</code>. </ul> Default value is `csv`.
-<a name="headerDefault"></a>default | * | Declares the value of the header that the server will use if none is provided. (Note: "default" has no meaning for required headers.) See http://json-schema.org/latest/json-schema-validation.html#anchor101. Unlike JSON Schema this value MUST conform to the defined [`type`](#headerDefault) for the header.
-<a name="headerMaximum"></a>maximum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
-<a name="headerMaximum"></a>exclusiveMaximum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
-<a name="headerMinimum"></a>minimum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
-<a name="headerExclusiveMinimum"></a>exclusiveMinimum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
-<a name="headerMaxLength"></a>maxLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor26.
-<a name="headerMinLength"></a>minLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor29.
-<a name="headerPattern"></a>pattern | `string` | See http://json-schema.org/latest/json-schema-validation.html#anchor33.
-<a name="headerMaxItems"></a>maxItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor42.
-<a name="headerMinItems"></a>minItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor45.
-<a name="headerUniqueItems"></a>uniqueItems | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor49.
-<a name="headerEnum"></a>enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76.
-<a name="headerMultipleOf"></a>multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14.
+The Header Object follows the structure of the [Parameter Object](#parameterObject), with the following changes:
-This object can be extended with [Specification Extensions](#specificationExtensions).
+1. `name` MUST NOT be specified, it is given in the [Headers Object](#headersObject).
+1. `in` MUST NOT be specified, it is implicitly in `header`.
+1. All traits that are affected by the location MUST follow the location of `header` (for example, [`style`](#parameterStyle)).
+1. `required` is by default `true`.
##### Header Object Example
@@ -2114,12 +2041,15 @@ A simple header with of an integer type:
```json
{
"description": "The number of allowed requests in the current period",
+ "schema": {
"type": "integer"
}
+}
```
```yaml
description: The number of allowed requests in the current period
+schema:
type: integer
```
@@ -2708,7 +2638,7 @@ See examples for expected behavior.
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
-<a name="xmlName"></a>name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within the Items Object (`items`), it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored.
+<a name="xmlName"></a>name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored.
<a name="xmlNamespace"></a>namespace | `string` | The URL of the namespace definition. Value SHOULD be in the form of a URL.
<a name="xmlPrefix"></a>prefix | `string` | The prefix to be used for the [name](#xmlName).
<a name="xmlAttribute"></a>attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`.

Updated Header Object, Removed Items Object