Skip to content

Commit 281f545

Browse files
webronwebron
authored
Merge pull request #897 from OAI/headers
Updated Header Object, removed Items Object
2 parents c833568 + 506cc78 commit 281f545

File tree

1 file changed

+27
-98
lines changed

1 file changed

+27
-98
lines changed

‎versions/3.0.md

+27-98
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,6 @@ Additional utilities can also take advantage of the resulting files, such as tes
4343
- [Request Body Object](#request-body-object)
4444
- [Content Object](#content-object)
4545
- [Content Type Object](#content-type-object)
46-
- [Items Object](#items-object)
4746
- [Responses Object](#responses-object)
4847
- [Response Object](#response-object)
4948
- [Headers Object](#headers-object)
@@ -741,7 +740,7 @@ A unique parameter is defined by a combination of a [name](#parameterName) and [
741740
There are four possible parameter types.
742741
* Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
743742
* Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
744-
* Header - Custom headers that are expected as part of the request.
743+
* Header - Custom headers that are expected as part of the request. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
745744
* Cookie - Used to pass a specific cookie value to the API.
746745

747746

@@ -1282,71 +1281,6 @@ encoding:
12821281
contentType: image/png, image/jpeg
12831282
```
12841283

1285-
#### <a name="itemsObject"></a>Items Object
1286-
1287-
A limited subset of JSON-Schema's items object.
1288-
It is used by parameter definitions.
1289-
1290-
##### Fixed Fields
1291-
Field Name | Type | Description
1292-
---|:---:|---
1293-
<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.
1294-
<a name="itemsFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details.
1295-
<a name="itemsItems"></a>items | [Items Object](#itemsObject) | **Required if [`type`](#itemsType) is "array".** Describes the type of items in the array.
1296-
<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`.
1297-
<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.
1298-
<a name="itemsMaximum"></a>maximum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
1299-
<a name="itemsMaximum"></a>exclusiveMaximum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
1300-
<a name="itemsMinimum"></a>minimum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
1301-
<a name="itemsExclusiveMinimum"></a>exclusiveMinimum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
1302-
<a name="itemsMaxLength"></a>maxLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor26.
1303-
<a name="itemsMinLength"></a>minLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor29.
1304-
<a name="itemsPattern"></a>pattern | `string` | See http://json-schema.org/latest/json-schema-validation.html#anchor33.
1305-
<a name="itemsMaxItems"></a>maxItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor42.
1306-
<a name="itemsMinItems"></a>minItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor45.
1307-
<a name="itemsUniqueItems"></a>uniqueItems | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor49.
1308-
<a name="itemsEnum"></a>enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76.
1309-
<a name="itemsMultipleOf"></a>multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14.
1310-
1311-
This object can be extended with [Specification Extensions](#specificationExtensions).
1312-
1313-
##### Items Object Examples
1314-
1315-
Items must be of type string and have the minimum length of 2 characters:
1316-
1317-
```json
1318-
{
1319-
"type": "string",
1320-
"minLength": 2
1321-
}
1322-
```
1323-
1324-
```yaml
1325-
type: string
1326-
minLength: 2
1327-
```
1328-
1329-
An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive):
1330-
1331-
```json
1332-
{
1333-
"type": "array",
1334-
"items": {
1335-
"type": "integer",
1336-
"minimum": 0,
1337-
"maximum": 63
1338-
}
1339-
}
1340-
```
1341-
1342-
```yaml
1343-
type: array
1344-
items:
1345-
type: integer
1346-
minimum: 0
1347-
maximum: 63
1348-
```
1349-
13501284
#### <a name="responsesObject"></a>Responses Object
13511285

13521286
A container for the expected responses of an operation.
@@ -1591,7 +1525,7 @@ myWebhook:
15911525

15921526

15931527
#### <a name="headersObject"></a>Headers Object
1594-
Lists the headers that can be sent as part of a response.
1528+
Lists the headers that can be sent as part of a response. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
15951529

15961530
##### Patterned Fields
15971531
Field Pattern | Type | Description
@@ -1606,29 +1540,38 @@ Rate-limit headers:
16061540
{
16071541
"X-Rate-Limit-Limit": {
16081542
"description": "The number of allowed requests in the current period",
1609-
"type": "integer"
1543+
"schema": {
1544+
"type": "integer"
1545+
}
16101546
},
16111547
"X-Rate-Limit-Remaining": {
16121548
"description": "The number of remaining requests in the current period",
1613-
"type": "integer"
1549+
"schema": {
1550+
"type": "integer"
1551+
}
16141552
},
16151553
"X-Rate-Limit-Reset": {
16161554
"description": "The number of seconds left in the current period",
1617-
"type": "integer"
1555+
"schema": {
1556+
"type": "integer"
1557+
}
16181558
}
16191559
}
16201560
```
16211561

16221562
```yaml
16231563
X-Rate-Limit-Limit:
16241564
description: The number of allowed requests in the current period
1625-
type: integer
1565+
schema:
1566+
type: integer
16261567
X-Rate-Limit-Remaining:
16271568
description: The number of remaining requests in the current period
1628-
type: integer
1569+
schema:
1570+
type: integer
16291571
X-Rate-Limit-Reset:
16301572
description: The number of seconds left in the current period
1631-
type: integer
1573+
schema:
1574+
type: integer
16321575
```
16331576

16341577
#### <a name="examplesObject"></a>Examples Object
@@ -2084,28 +2027,11 @@ In the above, the link for `UserCommitHistory` points to the operation `getUserC
20842027

20852028
#### <a name="headerObject"></a>Header Object
20862029

2087-
Field Name | Type | Description
2088-
---|:---:|---
2089-
<a name="headerDescription"></a>description | `string` | A short description of the header.
2090-
<a name="headerType"></a>type | `string` | **Required.** The type of the object. The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, or `"array"`.
2091-
<a name="headerFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#stType). See [Data Type Formats](#dataTypeFormat) for further details.
2092-
<a name="headerItems"></a>items | [Items Object](#itemsObject) | **Required if [`type`](#stType) is "array".** Describes the type of items in the array.
2093-
<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`.
2094-
<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.
2095-
<a name="headerMaximum"></a>maximum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
2096-
<a name="headerMaximum"></a>exclusiveMaximum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor17.
2097-
<a name="headerMinimum"></a>minimum | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
2098-
<a name="headerExclusiveMinimum"></a>exclusiveMinimum | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor21.
2099-
<a name="headerMaxLength"></a>maxLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor26.
2100-
<a name="headerMinLength"></a>minLength | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor29.
2101-
<a name="headerPattern"></a>pattern | `string` | See http://json-schema.org/latest/json-schema-validation.html#anchor33.
2102-
<a name="headerMaxItems"></a>maxItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor42.
2103-
<a name="headerMinItems"></a>minItems | `integer` | See http://json-schema.org/latest/json-schema-validation.html#anchor45.
2104-
<a name="headerUniqueItems"></a>uniqueItems | `boolean` | See http://json-schema.org/latest/json-schema-validation.html#anchor49.
2105-
<a name="headerEnum"></a>enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76.
2106-
<a name="headerMultipleOf"></a>multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14.
2030+
The Header Object follows the structure of the [Parameter Object](#parameterObject), with the following changes:
21072031

2108-
This object can be extended with [Specification Extensions](#specificationExtensions).
2032+
1. `name` MUST NOT be specified, it is given in the [Headers Object](#headersObject).
2033+
1. `in` MUST NOT be specified, it is implicitly in `header`.
2034+
1. All traits that are affected by the location MUST follow the location of `header` (for example, [`style`](#parameterStyle)).
21092035

21102036
##### Header Object Example
21112037

@@ -2114,13 +2040,16 @@ A simple header with of an integer type:
21142040
```json
21152041
{
21162042
"description": "The number of allowed requests in the current period",
2117-
"type": "integer"
2043+
"schema": {
2044+
"type": "integer"
2045+
}
21182046
}
21192047
```
21202048

21212049
```yaml
21222050
description: The number of allowed requests in the current period
2123-
type: integer
2051+
schema:
2052+
type: integer
21242053
```
21252054

21262055
#### <a name="tagObject"></a>Tag Object
@@ -2708,7 +2637,7 @@ See examples for expected behavior.
27082637
##### Fixed Fields
27092638
Field Name | Type | Description
27102639
---|:---:|---
2711-
<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.
2640+
<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.
27122641
<a name="xmlNamespace"></a>namespace | `string` | The URL of the namespace definition. Value SHOULD be in the form of a URL.
27132642
<a name="xmlPrefix"></a>prefix | `string` | The prefix to be used for the [name](#xmlName).
27142643
<a name="xmlAttribute"></a>attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`.

0 commit comments

Comments
 (0)