US House of Representatives API Rules

extends: spectral:oas
rules:
  congress-operation-ids-camel-case:
    description: Operation IDs must use camelCase naming
    message: Operation ID "{{value}}" should use camelCase (e.g., listBills, getMember)
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  congress-operations-have-summaries:
    description: All operations must have a summary
    message: Operation is missing a summary
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  congress-operations-have-tags:
    description: All operations should be tagged for grouping
    message: Operation is missing tags
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  congress-response-200-defined:
    description: All GET operations should define a 200 response
    message: GET operation is missing a 200 OK response
    severity: warn
    given: "$.paths[*][get]"
    then:
      field: responses.200
      function: truthy

  congress-v3-path-prefix:
    description: All paths should use the v3 versioning format
    message: API paths should reflect versioning
    severity: info
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: ".*\/v[0-9]+$"

  congress-format-param-documented:
    description: Format parameters should list valid values
    message: Format parameter should specify valid options
    severity: info
    given: "$.paths[*][*].parameters[?(@.name == 'format')]"
    then:
      field: schema.enum
      function: truthy

  congress-limit-param-max:
    description: Limit parameters should specify the maximum allowed value
    message: Limit parameter should specify maximum value (250)
    severity: info
    given: "$.paths[*][*].parameters[?(@.name == 'limit')]"
    then:
      field: schema.maximum
      function: truthy

  congress-security-scheme-defined:
    description: API should define authentication/security scheme
    message: API specification should define security schemes
    severity: warn
    given: "$.components.securitySchemes"
    then:
      function: truthy

  congress-info-contact-present:
    description: API should include contact information
    message: API info is missing contact details
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy

  congress-tags-title-case:
    description: Tags must use Title Case naming
    message: Tag "{{value}}" should use Title Case
    severity: warn
    given: "$.tags[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 &]*$"

  congress-path-versioned:
    description: API paths should not hardcode version numbers
    message: Version should be in server URL, not paths
    severity: info
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        notMatch: "^\/v[0-9]+"