{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"no-ambiguous-paths","__idx":0},"children":["no-ambiguous-paths"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ensures there are no ambiguous paths in your API descriptions."," ","When this rule is enabled, templated paths that support the same HTTP methods should not have ambiguous resolution."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["According to the OpenAPI specification:"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following paths are considered identical and invalid:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"/pets/{petId}\n/pets/{name}\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following may lead to ambiguous resolution:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"/{entity}/me\n/books/{id}\n","lang":"text"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"OAS"},"children":["OAS"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Compatibility"},"children":["Compatibility"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]}]}]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n\nRoot ==> Paths\n\nRoot ==> components\n\nstyle Paths fill:#codaf9,stroke:#0044d4,stroke-width:5px\n","diagramHtml":"

Root

Paths

components

","diagramHtmlDark":"

Root

Paths

components

"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-design-principles","__idx":1},"children":["API design principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ambiguity is all around us."," ","We need to minimize ambiguity in our API designs to avoid surprises."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consistent and predictable behavior is desirable for APIs, because it speeds up the onboarding process for API consumers and doesn't cause \"surprises\" in the developer experience."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ambiguity can creep in when a single path can satisfy two different path items."," ","Such paths are considered ambiguous and should be avoided, because API users and tools have no way of knowing which path is actually used."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":2},"children":["Configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["severity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Possible values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},". Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]}," (in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended"]}," configuration)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An example configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n no-ambiguous-paths: error\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given this configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n no-ambiguous-paths: error\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," ambiguous paths:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n '/{entity}/me':\n $ref: ./paths/example.yaml\n '/books/{id}':\n $ref: ./paths/example.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," paths:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n '/electronics/{id}':\n $ref: ./paths/example.yaml\n '/books/{id}':\n $ref: ./paths/example.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-rules","__idx":4},"children":["Related rules"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/no-identical-paths"},"children":["no-identical-paths"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":5},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/no-ambiguous-paths.ts"},"children":["Rule source"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/openapi-visual-reference/paths/"},"children":["Paths object docs"]}]}]}]},"frontmatter":{"slug":"/docs/cli/rules/oas/no-ambiguous-paths"},"tagList":[],"title":"no-ambiguous-paths","lastModified":"2026-10-05T04:46:46.000Z"}