URI Template support in parameters #804

darrelmiller · 2016-09-30T15:04:39Z

No description provided.

fehguy · 2016-09-30T16:11:35Z

versions/3.0.md

@@ -647,6 +647,9 @@ Field Name | Type | Description
 <a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. 
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
+<a name="parameterEscape"></a>escape | `boolean` | Determines whether the parameter value should have unallowed characters percent-encoded based the parameter location. The default value is `true`.


then:

/foo/{bar}

with bar = /baz/barf

we will have an issue with path matching

apply just to header & path

fehguy · 2016-09-30T16:12:59Z

versions/3.0.md

@@ -647,6 +647,9 @@ Field Name | Type | Description
 <a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. 
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
+<a name="parameterEscape"></a>escape | `boolean` | Determines whether the parameter value should have unallowed characters percent-encoded based the parameter location. The default value is `true`.
+<a name="parameterStyle"></a>style | `string` | Determines rendering rules based on [RFC 6570](https://tools.ietf.org/html/rfc6570). Valid values include "matrix", "label", "segment", "simple".  The style is only used when `in` has the value `path`. "matrix" refers to what RFC6570 calls "path-style".  Default value is "simple".
+<a name="parameterExplode"></a>explode | `boolean` | Indicates if the parameter values should rendered using the rules of the explode operator as defined in [RFC 6570](https://tools.ietf.org/html/rfc6570#section-2.2).  Default value is `false`.  


can we get rid of collectionFormat now? Let's review

fehguy · 2016-09-30T16:26:34Z

@darrelmiller making two (or so) changes then this will be merged

earth2marsh · 2016-09-30T16:26:56Z

This is more descriptive than 2.0, and it will increase the burden on tooling. For example, matrix parameters are most usually found in Java implementations, and now a project like a documentation generator might have to support matrix parameters in order to be "compliant" or "certified."

That's not a reason to stop the presses, just an observation. Hopefully we'll hear from tooling authors about this if it's a big problem.

…Issue-778

fehguy · 2017-01-24T18:04:23Z

versions/3.0.md

@@ -529,7 +529,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
      "items": {
        "type": "string"
      },
-      "collectionFormat": "csv"
+      "style": "comma-delimited"


change to camelCase

fehguy · 2017-01-24T18:04:34Z

versions/3.0.md

+matrix |  `string`, `array`, `object` |  `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) 
+label | `string`, `array`, `object` |  `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
+form |  `string`, `array`, `object` |  `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8)
+comma-delimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`.   


change to camelCase

fehguy · 2017-01-24T18:04:38Z

versions/3.0.md

+label | `string`, `array`, `object` |  `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
+form |  `string`, `array`, `object` |  `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8)
+comma-delimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`.   
+space-delimited | `array` | `query`, `path` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`. 


change to camelCase

fehguy · 2017-01-24T18:04:42Z

versions/3.0.md

+form |  `string`, `array`, `object` |  `query`| Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8)
+comma-delimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`.   
+space-delimited | `array` | `query`, `path` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`. 
+pipe-delimited | `array` | `query`, `path` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes`.


change to camelCase

fehguy · 2017-01-24T18:04:46Z

versions/3.0.md

+comma-delimited | `array` | `query`, `path` | Comma separated array values. This option replaces `collectionFormat` equal to `csv`.   
+space-delimited | `array` | `query`, `path` | Space separated array values. This option replaces `collectionFormat` equal to `ssv`. 
+pipe-delimited | `array` | `query`, `path` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes`.
+deep-object | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.


change to camelCase

fehguy · 2017-01-24T18:04:54Z

versions/3.0.md

+label | true | n/a | n/a |  n/a | .x=100.y=200
+form | false | . | value=hello | value=blue,black,brown | value=x,100,y,200
+form | true | n/a | n/a | value=blue&value=black&value=brown | x=100&y=200
+space-delimited | false | n/a | n/a | blue%20black%20brown | x%20100%20y%20200


change to camelCase

fehguy · 2017-01-24T18:04:58Z

versions/3.0.md

+form | false | . | value=hello | value=blue,black,brown | value=x,100,y,200
+form | true | n/a | n/a | value=blue&value=black&value=brown | x=100&y=200
+space-delimited | false | n/a | n/a | blue%20black%20brown | x%20100%20y%20200
+pipe-delimited | false | n/a | n/a | blue\|black\|brown | x\|100\|y\|200


change to camelCase

fehguy · 2017-01-24T18:05:10Z

versions/3.0.md

+form | true | n/a | n/a | value=blue&value=black&value=brown | x=100&y=200
+space-delimited | false | n/a | n/a | blue%20black%20brown | x%20100%20y%20200
+pipe-delimited | false | n/a | n/a | blue\|black\|brown | x\|100\|y\|200
+deep-object | true | n/a | n/a | n/a | person[name]=Bob&person[lastname]=Brown


change to camelCase

fehguy · 2017-01-24T18:05:14Z

versions/3.0.md

@@ -797,7 +834,7 @@ A header parameter with an array of 64 bit integer numbers:
      "format": "int64"
    }
  },
-  "collectionFormat": "csv"
+  "style": "comma-delimited"


change to camelCase

fehguy · 2017-01-24T18:05:18Z

versions/3.0.md

@@ -811,7 +848,7 @@ schema:
  items:
    type: integer
    format: int64
-  collectionFormat: csv
+style: comma-delimited


change to camelCase

fehguy · 2017-01-24T18:06:39Z

versions/3.0.md

+[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object`
+----------- | ------ | -------- | -------- | --------|-------
+matrix | false | ;value | ;value=hello | ;value=blue,black,brown | ;value=x,100,y200
+matrix | true | n/a | n/a | ;value=blue;value=black;value=brown | ;x=100;y=100


@darrelmiller you had to re-think why we have n/a here

webron · 2017-01-24T18:08:58Z

versions/3.0.md

 <a name="parameterFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details.
+<a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on the specified [`type`](#parameterType). 
+<a name="parameterAllowUnreserved"></a>allowReserved | `boolean` | Determines whether the parameter value should allow reserved characters `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.


Clarify the source for the character list.

webron · 2017-01-24T18:09:30Z

versions/3.0.md

 <a name="parameterFormat"></a>format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details.
+<a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on the specified [`type`](#parameterType). 
+<a name="parameterAllowUnreserved"></a>allowReserved | `boolean` | Determines whether the parameter value should allow reserved characters `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
+<a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. 


Explain that for an empty value or a primitive value explode is ignored.

webron · 2017-01-24T18:10:32Z

versions/3.0.md

+
+`style` | [`type`](#dataTypeType) |  `in` | Comments
+----------- | ------ | -------- | --------
+matrix |  `string`, `array`, `object` |  `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) 


Everywhere it says string as the type, it should be primitive (it can be any primitive)

webron · 2017-01-24T18:10:50Z

versions/3.0.md

+```
+The following table shows examples of how those values would be rendered.
+
+[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object`


Header should be primitive instead of string

webron · 2017-01-24T18:17:49Z

versions/3.0.md

+matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150
+label | false | .  | .blue |  .blue.black.brown | .R.100.G.200.B.150
+label | true | . | .blue |  .blue.black.brown | .R=100.G=200.B=150
+form | false | color= | color=blue | color=blue,black,brown | color=x,100,y,200


object example not updated

webron · 2017-01-24T18:18:02Z

versions/3.0.md

+label | false | .  | .blue |  .blue.black.brown | .R.100.G.200.B.150
+label | true | . | .blue |  .blue.black.brown | .R=100.G=200.B=150
+form | false | color= | color=blue | color=blue,black,brown | color=x,100,y,200
+form | true | color= | color=blue | color=blue&color=black&color=brown | x=100&y=200


object example not updated

webron · 2017-01-24T18:18:39Z

versions/3.0.md

+form | true | color= | color=blue | color=blue&color=black&color=brown | x=100&y=200
+spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150
+pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150
+deepObject | true | n/a | n/a | n/a | person[name]=Bob&person[lastname]=Brown


bassmanitram · 2017-02-17T15:44:34Z

Is there a "spec" of the templating features that this modification is intended to provide?
As it stands, for example, it doesn't seem to allow for "simple multi-segment" path parameterization (the cited "Dropbox" URI example cited in Issue 291)

darrelmiller · 2017-02-20T21:46:33Z

@bassmanitram multi-path segments parameters are not supported. I attempted to explain why here #892 (comment)

URI Template support in parameters

URI Template support in parameters

9952f5a

fehguy reviewed Sep 30, 2016

View reviewed changes

fehguy assigned darrelmiller Sep 30, 2016

fehguy added the OpenAPI.Next Proposal label Sep 30, 2016

darrelmiller added 4 commits October 7, 2016 20:50

Introduced prefix and separator

828583a

Merged

8616a99

Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into …

89a94bd

…Issue-778

uri template stuff

79cd9fa

darrelmiller mentioned this pull request Nov 23, 2016

Add support for Matrix type parameters #69

Closed

darrelmiller added 2 commits December 12, 2016 17:50

Style parameter

840de94

Updates to style parameter

c815866

fehguy reviewed Jan 24, 2017

View reviewed changes

webron reviewed Jan 24, 2017

View reviewed changes

Updates based on review

65e7d0b

webron reviewed Jan 24, 2017

View reviewed changes

darrelmiller added 5 commits January 24, 2017 13:45

Updates based on comments

5ba0fd8

Fixed camelCase in examples

3a8fcbb

changed primitive back to string in style example

9adb4aa

Added commaDelimited example

33b79aa

Updated parameter to have schema as a child property

b017b27

darrelmiller merged commit ce3a579 into OpenAPI.next Jan 27, 2017

darrelmiller deleted the Issue-778 branch January 27, 2017 21:22

This was referenced Feb 1, 2017

Freeform query string parameters #349

Closed

json array support for collectionFormat #437

Closed

Multidimensional arrays as parameters. #412

Closed

Parameter of type "associative array" #380

Closed

Proposal for URI Template support #778

Closed

This was referenced Feb 1, 2017

Parameter Object cleanup removed collectionFormat #754

Closed

Query parameters objects (like params[variable]=toto, ....) #595

Closed

Support for semantic path templating #576

Closed

Change collectionFormat default from csv to multi #405

Closed

This was referenced Feb 10, 2017

Path templating, multiple segments, and RFC 6570? #291

Closed

Allow the definition of an API path with template (like RFC6570) #394

Closed

RehanSaeed mentioned this pull request Feb 14, 2017

Supporting 'N' Number of Dynamic Query Parameters domaindrivendev/Swashbuckle.AspNetCore#298

Closed

AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019

Merge pull request OAI#804 from OAI/Issue-778

ad4f3cb

URI Template support in parameters

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

URI Template support in parameters #804

URI Template support in parameters #804

darrelmiller commented Sep 30, 2016

fehguy Sep 30, 2016

fehguy Sep 30, 2016

fehguy Sep 30, 2016

fehguy commented Sep 30, 2016

earth2marsh commented Sep 30, 2016

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

fehguy Jan 24, 2017

webron Jan 24, 2017

webron Jan 24, 2017

webron Jan 24, 2017

webron Jan 24, 2017

webron Jan 24, 2017

webron Jan 24, 2017

webron Jan 24, 2017

bassmanitram commented Feb 17, 2017

darrelmiller commented Feb 20, 2017

URI Template support in parameters #804

URI Template support in parameters #804

Conversation

darrelmiller commented Sep 30, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fehguy commented Sep 30, 2016

earth2marsh commented Sep 30, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bassmanitram commented Feb 17, 2017

darrelmiller commented Feb 20, 2017