Smithy · API Governance Rules

Smithy API Rules

Spectral linting rules defining API design standards and conventions for Smithy.

5 Rules error 1 warn 3 info 1

View Rules File View on GitHub

Rule Categories

smithy

Rules

error

smithy-operation-ids

All operations must have an operationId when represented as OpenAPI

$.paths[*][*]

warn

smithy-operation-tags

All operations must have at least one tag

$.paths[*][*]

warn

smithy-summary-title-case

Operation summaries must use Title Case

$.paths[*][*].summary

warn

smithy-no-trailing-slashes

API paths must not have trailing slashes

$.paths

info

smithy-versioned-paths

Smithy API paths should include version prefix for HTTP bindings

$.paths

Spectral Ruleset

# Smithy IDL Spectral-Style Ruleset
# Note: Smithy uses its own validation model (validators and linters) built into the Smithy CLI.
# These rules document Smithy's own quality conventions for API models.
extends: spectral:oas
rules:
  smithy-operation-ids:
    description: All operations must have an operationId when represented as OpenAPI
    severity: error
    given: "$.paths[*][*]"
    then:
      field: operationId
      function: truthy

  smithy-operation-tags:
    description: All operations must have at least one tag
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy

  smithy-summary-title-case:
    description: Operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]*$"

  smithy-no-trailing-slashes:
    description: API paths must not have trailing slashes
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        notMatch: "/$"

  smithy-versioned-paths:
    description: Smithy API paths should include version prefix for HTTP bindings
    severity: info
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^/v[0-9]"