feat(AIP-4222): define path_template syntax (#1067)

Author: noahdietz

aip/client-libraries/4222.md

@@ -50,6 +50,20 @@ rpc CreateTopic(CreateTopicRequest) {
 }
 ```
 
+The value of the field `field` **must** be one of the following:
+1. a name of a field in the top-level of the request message
+1. a dot-separated path of field names leading to a field in a sub-message of
+the request message e.g. `"book.author.name"` where `book` is a message field in
+the request message, `author` is a message field in the `book` message, and
+`name` is a `string` field in the `author` message
+
+The _actual field_ specified in the field `field` **must** have the following
+characteristics:
+- it is type `string`
+- it either has a path-like value format resembling a resource name or contains
+  an unstructured value that would be appropriate as an individual path segment
+  e.g. a `project_id`. 
+
 **Note:** An empty `google.api.routing` annotation is acceptable. It means that no
 routing headers should be generated for the RPC, when they otherwise would be
 e.g. implicitly from the `google.api.http` annotation.
@@ -89,7 +103,9 @@ routing_parameters {
   path_template: "{parent=**}"
 }
 ```
-NB: an omitted `path_template` field does not indicate that key-value pairs with empty values can be sent. It's merely a shorthand.
+
+**Note:** An omitted `path_template` field does not indicate that key-value
+pairs with empty values can be sent. It's merely a shorthand.
 
 When the user supplies an instance of `CreateTopicRequest` to the method, the
 client library **must** match all the routing parameters in the order specified
@@ -154,6 +170,54 @@ If none of the routing parameters matched their respective fields, the routing h
 Much like URL parameters, if there is more than one key-value pair to be sent, the `&`
 character is used as the separator.
 
+### `path_template` syntax
+
+As seen in the above examples, the `path_template` can use a variety of symbols
+that are interpreted by code generators during conversion to regular expressions
+or non-regular expression matcher implementations. The `path_template` consists
+of segments delimited by the segment delimiter. The syntax for `path_template`
+is as follows:
+
+- The only acceptable segment delimiter is `/`.
+  - The last symbol in a `path_template` **may** be a delimiter - it will be 
+    ignored.
+- A segment **must** be of one of the following types:
+  - `*`: A single-segment wildcard. Corresponds to 1 or more non-`/` symbols.
+    The regex describing it is `[^/]+`.
+    - A Single-segment wildcard typically represents a resource ID.
+  - `**`: A multi-segment wildcard. Corresponds to 0 or more segments. 
+    - A multi-segment wildcard **must** only appear as the final segment or
+      make up the entire `path_template`.
+    - In a multi-segment `path_template`, a multi-segment wildcard **must**
+      appear immediately following a segment delimiter. This delimiter is
+      consumed while matching so a `path_template` like `foo/**` matches all of
+      the following: `foo`, `foo/`, `foo/bar/baz`.
+    - In a multi-segment `path_template`, when used as the last segment the
+      regex describing it is `([:/].*)?`.
+    - When used as the entire `path_template`, the regex describing it is `.*`.
+    - Segment delimiters are consumed while matching, including any preceding
+      delimiter.
+  - `LITERAL`: A literal segment. A literal segment can contain any
+    alphanumeric symbol.
+    - A literal segment **must not** contain a symbol reserved in this syntax.
+    - Literal segments typically represent a resource collection ID or base
+      path.
+  - `{}`: A variable segment. This matches part of the path as specified by its
+    template.
+    - A variable segment can be either of the following:
+      - `{key}`, where `key` is the name to be used in the key-value pair of the
+        header
+      - `{key=template}`, where the `template` is the segment(s) (expressed in
+        this `path_template` syntax) to extract as the value paired with `key`
+    - A variable segment of just `{key}` defaults to a template of `*` which
+      matches 1 or more non-`/` symbols.
+      - While `{key=*}` is technicaly valid syntax, the simpler syntax of
+        `{key}` **should** be used.
+    - A variable segment **must not** contain other variable segments. This
+      syntax is not recursive.
+- A segment **must not** represent a complex resource ID as described in
+  [AIP-4231][]. A Generator **should** emit an error in this case.
+
 ## Implicit Routing Headers (`google.api.http`)
 
 **Note:** For an RPC annotated with the [`google.api.routing`][routing] annotation,
@@ -206,8 +270,10 @@ character is used as the separator.
 [http]: https://github.com/googleapis/googleapis/blob/master/google/api/http.proto
 [routing]: https://github.com/googleapis/googleapis/blob/master/google/api/routing.proto
 [rfc 6570 §3.2.2]: https://tools.ietf.org/html/rfc6570#section-3.2.2
+[AIP-4231]: ./4231.md#complex-resource-id-path-segments
 
 ## Changelog
+- **2023-07-07**: Include `path_template` syntax.
 - **2022-07-13**: Updated to include the new `google.api.routing` annotation.
 - **2020-04-21**: Explicitly parse path variables missing a trailing segment.
 - **2019-11-27**: Include `additional_bindings` as a request parameter source.