Vertiv API Rules

extends: spectral:oas
rules:
  vertiv-operation-ids-kebab-case:
    description: Operation IDs must use camelCase as per Vertiv API conventions
    message: "Operation ID '{{value}}' must use camelCase"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  vertiv-paths-kebab-case:
    description: Path segments must use kebab-case
    message: "Path '{{path}}' must use kebab-case segments"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{][a-z0-9-{}]*)*$"

  vertiv-require-auth-token-header:
    description: >-
      All operations (except /auth POST) must declare X-Auth-Token security
    message: "Operation must require session token authentication"
    severity: warn
    given: "$.paths[?(@property != '/auth')][get,put,patch,delete].security"
    then:
      function: truthy

  vertiv-response-200-must-have-schema:
    description: All 200 responses must include a schema definition
    message: "200 response must include a content schema"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete].responses['200'].content[*]"
    then:
      field: schema
      function: truthy

  vertiv-require-operation-tags:
    description: All operations must have at least one tag for grouping
    message: "Operations must have at least one tag"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: length
      functionOptions:
        min: 1

  vertiv-require-operation-description:
    description: All operations must have a description
    message: "Operation must include a description"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  vertiv-error-response-schema:
    description: >-
      All non-2xx responses should reference the shared Error schema
    message: "Error responses should use the shared Error schema"
    severity: info
    given: "$.paths[*][get,post,put,patch,delete].responses[4*,5*].content['application/json']"
    then:
      field: schema
      function: truthy

  vertiv-status-enum-values:
    description: Status fields must use Vertiv's standard status enum values
    message: "Status enum must include standard Vertiv status values"
    severity: info
    given: "$.components.schemas[*].properties.status.enum"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            enum:
              - NORMAL
              - ALARM
              - WARNING

  vertiv-require-contact:
    description: API info must include contact information
    message: "API info should include contact details"
    severity: info
    given: "$.info"
    then:
      field: contact
      function: truthy

  vertiv-server-variable-description:
    description: Server variables must have a description
    message: "Server variable must have a description"
    severity: warn
    given: "$.servers[*].variables[*]"
    then:
      field: description
      function: truthy