Add support for URI templates

.chronus/changes/uri-templates-2024-6-24-20-7-39.md

@@ -0,0 +1,12 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+`@route` can now take a uri template as defined by [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
+
+  ```tsp
+  @route("files{+path}") download(path: string): void;
+  ```

.chronus/changes/uri-templates-2024-6-24-21-37-52.md

@@ -0,0 +1,9 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+  - "@typespec/rest"
+---
+
+Add support for URI templates in routes

.chronus/changes/uri-templates-2024-6-25-9-3-39.md

@@ -0,0 +1,13 @@
+---
+changeKind: deprecation
+packages:
+  - "@typespec/http"
+---
+
+Deprecated `@query({format: })` option. Use `@query(#{explode: true})` instead of `form` or `multi` format. Previously `csv`/`simple` is the default now.
+  Decorator is also expecting an object value now instead of a model. A deprecation warning with a codefix will help migrating.
+
+  ```diff
+  - @query({format: "form"}) select: string[];
+  + @query(#{explode: true}) select: string[];
+  ```

docs/libraries/http/reference/data-types.md

@@ -466,6 +466,21 @@ model TypeSpec.Http.PasswordFlow
 | refreshUrl? | `string`                                | the refresh URL                   |
 | scopes?     | `string[]`                              | list of scopes for the credential |
 
+### `PathOptions` {#TypeSpec.Http.PathOptions}
+
+```typespec
+model TypeSpec.Http.PathOptions
+```
+
+#### Properties
+
+| Name           | Type                                                      | Description                                                                                                                                                                                                                                  |
+| -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| name?          | `string`                                                  | Name of the parameter in the uri template.                                                                                                                                                                                                   |
+| explode?       | `boolean`                                                 | When interpolating this parameter in the case of array or object expand each value using the given style.<br />Equivalent of adding `*` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) |
+| style?         | `"simple" \| "label" \| "matrix" \| "fragment" \| "path"` | Different interpolating styles for the path parameter.<br />- `simple`: No special encoding.<br />- `label`: Using `.` separator.<br />- `matrix`: `;` as separator.<br />- `fragment`: `#` as separator.<br />- `path`: `/` as separator.   |
+| allowReserved? | `boolean`                                                 | When interpolating this parameter do not encode reserved characters.<br />Equivalent of adding `+` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)                                      |
+
 ### `PlainData` {#TypeSpec.Http.PlainData}
 
 Produces a new model with the same properties as T, but with `@query`,

docs/libraries/http/reference/decorators.md

@@ -278,7 +278,7 @@ None
 Explicitly specify that this property is to be interpolated as a path parameter.
 
 ```typespec
-@TypeSpec.Http.path(paramName?: valueof string)
+@TypeSpec.Http.path(paramNameOrOptions?: valueof string | TypeSpec.Http.PathOptions)
 ```
 
 #### Target
@@ -287,9 +287,9 @@ Explicitly specify that this property is to be interpolated as a path parameter.
 
 #### Parameters
 
-| Name      | Type             | Description                                         |
-| --------- | ---------------- | --------------------------------------------------- |
-| paramName | `valueof string` | Optional name of the parameter in the url template. |
+| Name               | Type                                          | Description                                                    |
+| ------------------ | --------------------------------------------- | -------------------------------------------------------------- |
+| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the uri template or options. |
 
 #### Examples
 
@@ -375,11 +375,7 @@ op list(
 
 ### `@route` {#@TypeSpec.Http.route}
 
-Defines the relative route URI for the target operation
-
-The first argument should be a URI fragment that may contain one or more path parameter fields.
-If the namespace or interface that contains the operation is also marked with a `@route` decorator,
-it will be used as a prefix to the route URI of the operation.
+Defines the relative route URI template for the target operation as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
 
 `@route` can only be applied to operations, namespaces, and interfaces.
 
@@ -393,16 +389,30 @@ it will be used as a prefix to the route URI of the operation.
 
 #### Parameters
 
-| Name    | Type             | Description                                                                                                                                  |
-| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| path    | `valueof string` | Relative route path. Cannot include query parameters.                                                                                        |
-| options | `{...}`          | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. |
+| Name    | Type             | Description                                                                                                                                               |
+| ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| path    | `valueof string` | Relative route path. Cannot include query parameters.                                                                                                     |
+| options | `{...}`          | _DEPRECATED_ Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. |
 
 #### Examples
 
+##### Simple path parameter
+
 ```typespec
-@route("/widgets")
-op getWidget(@path id: string): Widget;
+@route("/widgets/{id}") op getWidget(@path id: string): Widget;
+```
+
+##### Reserved characters
+
+```typespec
+@route("/files{+path}") op getFile(@path path: string): bytes;
+```
+
+##### Query parameter
+
+```typespec
+@route("/files") op list(select?: string, filter?: string): Widget[];
+@route("/files{?select,filter}") op listFullUriTemplateselect?: string, filter?: string): Widget[];
 ```
 
 ### `@server` {#@TypeSpec.Http.server}

docs/libraries/http/reference/index.mdx

@@ -83,6 +83,7 @@ npm install --save-peer @typespec/http
 - [`OkResponse`](./data-types.md#TypeSpec.Http.OkResponse)
 - [`OpenIdConnectAuth`](./data-types.md#TypeSpec.Http.OpenIdConnectAuth)
 - [`PasswordFlow`](./data-types.md#TypeSpec.Http.PasswordFlow)
+- [`PathOptions`](./data-types.md#TypeSpec.Http.PathOptions)
 - [`PlainData`](./data-types.md#TypeSpec.Http.PlainData)
 - [`QueryOptions`](./data-types.md#TypeSpec.Http.QueryOptions)
 - [`Response`](./data-types.md#TypeSpec.Http.Response)

packages/http/README.md

@@ -326,7 +326,7 @@ None
 Explicitly specify that this property is to be interpolated as a path parameter.
 
 ```typespec
-@TypeSpec.Http.path(paramName?: valueof string)
+@TypeSpec.Http.path(paramNameOrOptions?: valueof string | TypeSpec.Http.PathOptions)
 ```
 
 ##### Target
@@ -335,9 +335,9 @@ Explicitly specify that this property is to be interpolated as a path parameter.
 
 ##### Parameters
 
-| Name      | Type             | Description                                         |
-| --------- | ---------------- | --------------------------------------------------- |
-| paramName | `valueof string` | Optional name of the parameter in the url template. |
+| Name               | Type                                          | Description                                                    |
+| ------------------ | --------------------------------------------- | -------------------------------------------------------------- |
+| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the uri template or options. |
 
 ##### Examples
 
@@ -423,11 +423,7 @@ op list(
 
 #### `@route`
 
-Defines the relative route URI for the target operation
-
-The first argument should be a URI fragment that may contain one or more path parameter fields.
-If the namespace or interface that contains the operation is also marked with a `@route` decorator,
-it will be used as a prefix to the route URI of the operation.
+Defines the relative route URI template for the target operation as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
 
 `@route` can only be applied to operations, namespaces, and interfaces.
 
@@ -441,16 +437,30 @@ it will be used as a prefix to the route URI of the operation.
 
 ##### Parameters
 
-| Name    | Type             | Description                                                                                                                                  |
-| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| path    | `valueof string` | Relative route path. Cannot include query parameters.                                                                                        |
-| options | `{...}`          | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. |
+| Name    | Type             | Description                                                                                                                                               |
+| ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| path    | `valueof string` | Relative route path. Cannot include query parameters.                                                                                                     |
+| options | `{...}`          | _DEPRECATED_ Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. |
 
 ##### Examples
 
+###### Simple path parameter
+
 ```typespec
-@route("/widgets")
-op getWidget(@path id: string): Widget;
+@route("/widgets/{id}") op getWidget(@path id: string): Widget;
+```
+
+###### Reserved characters
+
+```typespec
+@route("/files{+path}") op getFile(@path path: string): bytes;
+```
+
+###### Query parameter
+
+```typespec
+@route("/files") op list(select?: string, filter?: string): Widget[];
+@route("/files{?select,filter}") op listFullUriTemplateselect?: string, filter?: string): Widget[];
 ```
 
 #### `@server`

packages/http/generated-defs/TypeSpec.Http.ts

@@ -7,6 +7,19 @@ import type {
   Type,
 } from "@typespec/compiler";
 
+export interface QueryOptions {
+  readonly name?: string;
+  readonly explode?: boolean;
+  readonly format?: "multi" | "csv" | "ssv" | "tsv" | "simple" | "form" | "pipes";
+}
+
+export interface PathOptions {
+  readonly name?: string;
+  readonly explode?: boolean;
+  readonly style?: "simple" | "label" | "matrix" | "fragment" | "path";
+  readonly allowReserved?: boolean;
+}
+
 /**
  * Specify the status code for this response. Property type must be a status code integer or a union of status code integer.
  *
@@ -73,13 +86,13 @@ export type HeaderDecorator = (
 export type QueryDecorator = (
   context: DecoratorContext,
   target: ModelProperty,
-  queryNameOrOptions?: Type
+  queryNameOrOptions?: string | QueryOptions
 ) => void;
 
 /**
  * Explicitly specify that this property is to be interpolated as a path parameter.
  *
- * @param paramName Optional name of the parameter in the url template.
+ * @param paramNameOrOptions Optional name of the parameter in the uri template or options.
  * @example
  * ```typespec
  * @route("/read/{explicit}/things/{implicit}")
@@ -89,7 +102,7 @@ export type QueryDecorator = (
 export type PathDecorator = (
   context: DecoratorContext,
   target: ModelProperty,
-  paramName?: string
+  paramNameOrOptions?: string | PathOptions
 ) => void;
 
 /**
@@ -260,20 +273,25 @@ export type IncludeInapplicableMetadataInPayloadDecorator = (
 ) => void;
 
 /**
- * Defines the relative route URI for the target operation
- *
- * The first argument should be a URI fragment that may contain one or more path parameter fields.
- * If the namespace or interface that contains the operation is also marked with a `@route` decorator,
- * it will be used as a prefix to the route URI of the operation.
+ * Defines the relative route URI template for the target operation as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
  *
  * `@route` can only be applied to operations, namespaces, and interfaces.
  *
  * @param path Relative route path. Cannot include query parameters.
- * @param options Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations.
- * @example
+ * @param options _DEPRECATED_ Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations.
+ * @example Simple path parameter
+ *
  * ```typespec
- * @route("/widgets")
- * op getWidget(@path id: string): Widget;
+ * @route("/widgets/{id}") op getWidget(@path id: string): Widget;
+ * ```
+ * @example Reserved characters
+ * ```typespec
+ * @route("/files{+path}") op getFile(@path path: string): bytes;
+ * ```
+ * @example Query parameter
+ * ```typespec
+ * @route("/files") op list(select?: string, filter?: string): Widget[];
+ * @route("/files{?select,filter}") op listFullUriTemplateselect?: string, filter?: string): Widget[];
  * ```
  */
 export type RouteDecorator = (