no-ambiguous-paths

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.

According to the OpenAPI specification:

The following paths are considered identical and invalid:

/pets/{petId} /pets/{name}

The following may lead to ambiguous resolution:

/{entity}/me /books/{id}

API design principles

Ambiguity is all around us. We need to minimize ambiguity in our API designs to avoid surprises.

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.

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.

Configuration

An example configuration:

rules:
  no-ambiguous-paths: error

Examples

Given this configuration:

rules:
  no-ambiguous-paths: error

Example of incorrect ambiguous paths:

paths:
  '/{entity}/me':
    $ref: ./paths/example.yaml
  '/books/{id}':
    $ref: ./paths/example.yaml

Example of correct paths:

paths:
  '/electronics/{id}':
    $ref: ./paths/example.yaml
  '/books/{id}':
    $ref: ./paths/example.yaml

Related rules

• no-identical-paths

Resources

• Rule source
• Paths object docs