W3C API Rules

extends: spectral:oas
rules:
  # W3C API-specific rules for the W3C API (api.w3.org)
  w3c-api-info-contact:
    description: W3C API definitions should include contact information.
    severity: info
    given: "$.info"
    then:
      field: contact
      function: truthy

  w3c-api-operation-summary-title-case:
    description: Operation summaries should use Title Case.
    message: "Summary '{{value}}' should use Title Case."
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z]"

  w3c-api-has-description:
    description: All operations should have a description for documentation quality.
    severity: info
    given: "$.paths[*][*]"
    then:
      field: description
      function: truthy

  w3c-api-response-defined:
    description: Every operation should define at least one response.
    severity: warn
    given: "$.paths[*][*].responses"
    then:
      function: truthy

  w3c-api-200-response:
    description: GET operations should have a 200 response defined.
    severity: warn
    given: "$.paths[*].get.responses"
    then:
      field: "200"
      function: truthy

  w3c-api-path-versioned:
    description: W3C API paths should be versioned.
    severity: info
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "/[v][0-9]"

  w3c-api-tags-defined:
    description: Operations should be tagged for logical grouping.
    severity: info
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy