Acceptance Criteria API Rules

extends: spectral:oas
rules:
  # Authentication Rules
  ac-require-security-scheme:
    description: APIs managing acceptance criteria must require authentication
    message: "Operation '{{path}}' must define security requirements"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: security
      function: truthy

  # Path Naming Rules
  ac-path-kebab-case:
    description: API paths must use kebab-case naming
    message: "Path '{{value}}' must use kebab-case"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9-]+({[a-zA-Z]+})?)*$"

  ac-no-trailing-slash:
    description: API paths must not have trailing slashes
    message: "Path '{{value}}' must not have a trailing slash"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        notMatch: "/$"

  # Operation Rules
  ac-operations-require-summary:
    description: All operations must have a summary
    message: "Operation at '{{path}}' must have a summary"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  ac-operations-require-operation-id:
    description: All operations must have an operationId
    message: "Operation at '{{path}}' must have an operationId"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  ac-operation-id-camel-case:
    description: OperationIds must use camelCase
    message: "OperationId '{{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]*$"

  ac-operations-require-tags:
    description: All operations must have at least one tag
    message: "Operation at '{{path}}' must have at least one tag"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  ac-operations-require-description:
    description: All operations should have a description
    message: "Operation at '{{path}}' should have a description"
    severity: info
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  # Response Rules
  ac-require-200-response:
    description: GET operations must define a 200 response
    message: "GET operation at '{{path}}' must define a 200 response"
    severity: error
    given: "$.paths[*].get.responses"
    then:
      field: "200"
      function: truthy

  ac-require-201-on-post:
    description: POST operations should define a 201 created response
    message: "POST operation at '{{path}}' should define a 201 response"
    severity: warn
    given: "$.paths[*].post.responses"
    then:
      field: "201"
      function: truthy

  ac-require-401-response:
    description: Operations must define a 401 unauthorized response
    message: "Operation at '{{path}}' must define a 401 response"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "401"
      function: truthy

  ac-require-404-on-parameterized-paths:
    description: Operations on parameterized paths must define a 404 response
    message: "Operation at '{{path}}' must define a 404 response"
    severity: warn
    given: "$.paths[?(@~.match(/\\{.*\\}/))][get,put,patch,delete].responses"
    then:
      field: "404"
      function: truthy

  ac-require-500-response:
    description: All operations must define a 500 server error response
    message: "Operation at '{{path}}' must define a 500 response"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "500"
      function: truthy

  # Schema Rules
  ac-schema-require-description:
    description: All schema components must have a description
    message: "Schema '{{path}}' must have a description"
    severity: warn
    given: "$.components.schemas[*]"
    then:
      field: description
      function: truthy

  ac-schema-properties-require-description:
    description: Schema properties should have descriptions for self-documenting APIs
    message: "Property at '{{path}}' should have a description"
    severity: info
    given: "$.components.schemas[*].properties[*]"
    then:
      field: description
      function: truthy

  ac-require-id-property:
    description: Resource schemas must include an id property
    message: "Schema '{{path}}' must include an 'id' property"
    severity: warn
    given: "$.components.schemas[?([email protected] =~ /(List|Request)$/)]"
    then:
      field: properties.id
      function: truthy

  ac-timestamp-format:
    description: Timestamp fields must use date-time format
    message: "Timestamp property at '{{path}}' must use format: date-time"
    severity: error
    given: "$.components.schemas[*].properties[?(@.description =~ /[Tt]imestamp|At$|[Dd]ate/)]"
    then:
      field: format
      function: enumeration
      functionOptions:
        values:
          - date-time
          - date

  # Acceptance Criteria Specific Rules
  ac-gherkin-given-when-then:
    description: Gherkin-format acceptance criteria must include given, when, and then fields
    message: "Gherkin acceptance criterion at '{{path}}' should include 'given', 'when', and 'then' properties"
    severity: info
    given: "$.components.schemas.AcceptanceCriterion.properties"
    then:
      function: schema
      functionOptions:
        schema:
          required: [given, when, then]

  ac-status-enum-values:
    description: Status fields must use defined enum values
    message: "Status property at '{{path}}' must define enum values"
    severity: warn
    given: "$.components.schemas[*].properties.status"
    then:
      field: enum
      function: truthy

  ac-priority-enum-values:
    description: Priority fields must use defined enum values
    message: "Priority property at '{{path}}' must define enum values"
    severity: warn
    given: "$.components.schemas[*].properties.priority"
    then:
      field: enum
      function: truthy

  # Content Type Rules
  ac-require-json-request-body:
    description: Request bodies must use application/json content type
    message: "Request body at '{{path}}' must use application/json"
    severity: error
    given: "$.paths[*][post,put,patch].requestBody.content"
    then:
      field: application/json
      function: truthy

  ac-require-json-response:
    description: Success responses must return application/json
    message: "Response at '{{path}}' must return application/json"
    severity: error
    given: "$.paths[*][get,post,put,patch].responses[200,201].content"
    then:
      field: application/json
      function: truthy

  # Pagination Rules
  ac-list-responses-require-total:
    description: List schema responses must include a total count
    message: "List schema '{{path}}' must include a 'total' property"
    severity: warn
    given: "$.components.schemas[?(@.title =~ /List$/)]"
    then:
      field: properties.total
      function: truthy

  ac-list-responses-require-page:
    description: List schema responses must include page for pagination
    message: "List schema '{{path}}' must include a 'page' property"
    severity: warn
    given: "$.components.schemas[?(@.title =~ /List$/)]"
    then:
      field: properties.page
      function: truthy

  # Info Rules
  ac-info-require-version:
    description: API spec must include a version
    message: "API info must include a version"
    severity: error
    given: "$.info"
    then:
      field: version
      function: truthy

  ac-info-require-description:
    description: API spec must include a description
    message: "API info must include a description"
    severity: error
    given: "$.info"
    then:
      field: description
      function: truthy

  ac-info-require-contact:
    description: API spec should include contact information
    message: "API info should include a contact object"
    severity: info
    given: "$.info"
    then:
      field: contact
      function: truthy