VTEX · API Governance Rules

VTEX API Rules

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

10 Rules warn 5 info 5
View Rules File View on GitHub

Rule Categories

vtex

Rules

warn
vtex-operation-summary-title-case
Operation summaries must use Title Case.
$.paths[*][*].summary
info
vtex-operation-id-kebab-case
operationId should use kebab-case or camelCase consistently.
$.paths[*][*].operationId
warn
vtex-has-tags
Every operation must have at least one tag for grouping.
$.paths[*][*]
info
vtex-server-variable-account-name
VTEX APIs should use {accountName} server variable for multi-tenancy.
$.servers[*].variables
warn
vtex-response-200-defined
Every GET operation should define a 200 response.
$.paths[*].get.responses
warn
vtex-request-body-post
POST operations should define a request body.
$.paths[*].post
warn
vtex-security-defined
VTEX APIs should define security schemes for authentication.
$.components.securitySchemes
info
vtex-info-contact
API info should include contact information.
$.info
info
vtex-path-kebab-case
Path segments should use kebab-case or camelCase, not underscores.
$.paths
info
vtex-no-empty-descriptions
Operations should have non-empty descriptions.
$.paths[*][*].description

Spectral Ruleset

Raw ↑ 
extends: spectral:oas
rules:
  # VTEX-specific naming conventions
  vtex-operation-summary-title-case:
    description: Operation summaries must use Title Case.
    message: "Summary '{{value}}' should use Title Case."
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z]"

  vtex-operation-id-kebab-case:
    description: operationId should use kebab-case or camelCase consistently.
    severity: info
    given: "$.paths[*][*].operationId"
    then:
      function: truthy

  vtex-has-tags:
    description: Every operation must have at least one tag for grouping.
    message: "Operation '{{path}}' must have at least one tag."
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy

  vtex-server-variable-account-name:
    description: VTEX APIs should use {accountName} server variable for multi-tenancy.
    severity: info
    given: "$.servers[*].variables"
    then:
      field: accountName
      function: truthy

  vtex-response-200-defined:
    description: Every GET operation should define a 200 response.
    severity: warn
    given: "$.paths[*].get.responses"
    then:
      field: "200"
      function: truthy

  vtex-request-body-post:
    description: POST operations should define a request body.
    severity: warn
    given: "$.paths[*].post"
    then:
      field: requestBody
      function: truthy

  vtex-security-defined:
    description: VTEX APIs should define security schemes for authentication.
    severity: warn
    given: "$.components.securitySchemes"
    then:
      function: truthy

  vtex-info-contact:
    description: API info should include contact information.
    severity: info
    given: "$.info"
    then:
      field: contact
      function: truthy

  vtex-path-kebab-case:
    description: Path segments should use kebab-case or camelCase, not underscores.
    severity: info
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        notMatch: "^.*_[a-z].*$"

  vtex-no-empty-descriptions:
    description: Operations should have non-empty descriptions.
    severity: info
    given: "$.paths[*][*].description"
    then:
      function: truthy