SPAN · API Governance Rules

SPAN API Rules

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

5 Rules error 1 warn 4

View Rules File View on GitHub

Rule Categories

span

Rules

warn

span-paths-versioned

All SPAN REST paths must begin with /api/v1/.

$.paths

warn

span-paths-kebab-case

SPAN path segments use kebab-case (lowercase with hyphens).

$.paths

error

span-bearer-security

SPAN OpenAPI must declare HTTPBearer security scheme.

$.components.securitySchemes

warn

span-operation-summary

SPAN operations must have a summary.

$.paths.*[get,post,put,delete,patch]

warn

span-json-only

SPAN responses are application/json.

$.paths.*[get,post,put,delete,patch].responses.*.content

Spectral Ruleset

extends: [[spectral:oas, all]]
rules:
  # SPAN paths are versioned at /api/v1/
  span-paths-versioned:
    description: All SPAN REST paths must begin with /api/v1/.
    severity: warn
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^/api/v1/"
  # SPAN uses kebab-case for path segments
  span-paths-kebab-case:
    description: SPAN path segments use kebab-case (lowercase with hyphens).
    severity: warn
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^/api/v1(/[a-z0-9-]+|/\\{[a-zA-Z_]+\\})*$"
  # SPAN endpoints use HTTP Bearer JWT authentication
  span-bearer-security:
    description: SPAN OpenAPI must declare HTTPBearer security scheme.
    severity: error
    given: "$.components.securitySchemes"
    then:
      field: HTTPBearer
      function: truthy
  # Operations should be tagless-but-summarized
  span-operation-summary:
    description: SPAN operations must have a summary.
    severity: warn
    given: "$.paths.*[get,post,put,delete,patch]"
    then:
      field: summary
      function: truthy
  # JSON-only API
  span-json-only:
    description: SPAN responses are application/json.
    severity: warn
    given: "$.paths.*[get,post,put,delete,patch].responses.*.content"
    then:
      field: "application/json"
      function: truthy