Merge pull request #1204 from OAI/path-templating-clarifications

Clarified path matching

Author: RobDolinMS

versions/3.0.md

@@ -632,10 +632,33 @@ The path is appended to the URL from the [`Server Object`](#serverObject) in ord
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed.
+<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
+##### Path Templating Matching
+
+Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:
+
+```
+  /pets/{petId}
+  /pets/mine
+```
+
+The following paths are considered identical and invalid:
+
+```
+  /pets/{petId}
+  /pets/{name}
+```
+
+The following may lead to ambiguous resolution:
+
+```
+  /{entity}/me
+  /books/{id}
+```
+
 ##### Paths Object Example
 
 ```json