Runa · API Governance Rules

Runa API Rules

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

9 Rules error 1 warn 7 info 1

View Rules File View on GitHub

Rule Categories

runa

Rules

warn

runa-operation-ids-camel-case

All operationIds must use camelCase naming convention.

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

warn

runa-tags-title-case

All tags must use Title Case.

$.tags[*].name

warn

runa-api-key-header

All operations must use X-Api-Key apiKey authentication.

$.components.securitySchemes.apiKeyAuth

warn

runa-idempotency-key-on-orders

Order creation endpoint should document X-Idempotency-Key header.

$.paths.*.post.parameters[?(@.name=='X-Idempotency-Key')]

warn

runa-paths-kebab-case

All path segments must use kebab-case.

$.paths

error

runa-response-200-defined

All operations must define a 200 response.

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

warn

runa-401-defined

All secured endpoints must define a 401 response.

$.paths.*[get,post].responses

warn

runa-summaries-title-case

Operation summaries must use Title Case.

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

info

runa-versioned-api

API version should be expressed in the server URL path.

$.servers[*].url

Spectral Ruleset

rules:
  runa-operation-ids-camel-case:
    description: All operationIds must use camelCase naming convention.
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  runa-tags-title-case:
    description: All tags must use Title Case.
    severity: warn
    given: "$.tags[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]*$"

  runa-api-key-header:
    description: All operations must use X-Api-Key apiKey authentication.
    severity: warn
    given: "$.components.securitySchemes.apiKeyAuth"
    then:
      function: schema
      functionOptions:
        schema:
          properties:
            name:
              const: X-Api-Key

  runa-idempotency-key-on-orders:
    description: Order creation endpoint should document X-Idempotency-Key header.
    severity: warn
    given: "$.paths.*.post.parameters[?(@.name=='X-Idempotency-Key')]"
    then:
      function: schema
      functionOptions:
        schema:
          properties:
            in:
              const: header

  runa-paths-kebab-case:
    description: All path segments must use kebab-case.
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}-]+)+$"

  runa-response-200-defined:
    description: All operations must define a 200 response.
    severity: error
    given: "$.paths.*[get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          required:
            - "200"

  runa-401-defined:
    description: All secured endpoints must define a 401 response.
    severity: warn
    given: "$.paths.*[get,post].responses"
    then:
      function: schema
      functionOptions:
        schema:
          required:
            - "401"

  runa-summaries-title-case:
    description: Operation summaries must use Title Case.
    severity: warn
    given: "$.paths.*[get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z]"

  runa-versioned-api:
    description: API version should be expressed in the server URL path.
    severity: info
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "/v[0-9]"