DiscGolfAPI API Rules

extends: spectral:oas
rules:

  discgolfapi-operations-have-tags:
    description: All DiscGolfAPI operations must have at least one tag
    severity: warn
    given: "$.paths[*][get,put,post,delete,patch]"
    then:
      field: tags
      function: truthy

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

  discgolfapi-operations-have-operation-ids:
    description: All DiscGolfAPI operations must have an operationId
    severity: error
    given: "$.paths[*][get,put,post,delete,patch]"
    then:
      field: operationId
      function: truthy

  discgolfapi-summaries-title-case:
    description: DiscGolfAPI operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][get,put,post,delete,patch].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*([ ][A-Z][a-zA-Z0-9]*)*$"

  discgolfapi-operations-have-descriptions:
    description: All DiscGolfAPI operations must have a description
    severity: warn
    given: "$.paths[*][get,put,post,delete,patch]"
    then:
      field: description
      function: truthy

  discgolfapi-operations-define-429:
    description: Public read endpoints should document a 429 Too Many Requests response so clients can implement backoff
    severity: warn
    given: "$.paths[*][get]"
    then:
      field: "responses.429"
      function: truthy

  discgolfapi-operations-define-500:
    description: Public read endpoints should document a 500 server error response
    severity: warn
    given: "$.paths[*][get]"
    then:
      field: "responses.500"
      function: truthy

  discgolfapi-responses-have-descriptions:
    description: All response objects must have a description
    severity: warn
    given: "$.paths[*][*].responses[*]"
    then:
      field: description
      function: truthy

  discgolfapi-path-parameters-required:
    description: All path parameters must be marked as required
    severity: error
    given: "$.paths[*][*].parameters[?(@.in == 'path')]"
    then:
      field: required
      function: truthy

  discgolfapi-components-schemas-described:
    description: All component schemas should have either a description or a clear structural shape
    severity: info
    given: "$.components.schemas[*]"
    then:
      field: description
      function: truthy

  discgolfapi-list-endpoints-use-pagination:
    description: List endpoints (limit/offset) must define both Limit and Offset parameters
    severity: info
    given: "$.paths['/courses'].get.parameters"
    then:
      function: length
      functionOptions:
        min: 4

  discgolfapi-response-envelope-attribution:
    description: List and detail responses should advertise the attribution and licence fields in the common envelope schema
    severity: info
    given: "$.components.schemas.CommonEnvelope.required"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            const: attribution

  discgolfapi-stable-id-pattern:
    description: Course path parameter must declare the stable crs_ ID pattern
    severity: warn
    given: "$.components.parameters.CourseId.schema"
    then:
      field: pattern
      function: truthy

  discgolfapi-info-license-required:
    description: The info object must declare a licence so consumers know reuse terms
    severity: error
    given: "$.info"
    then:
      field: license
      function: truthy

  discgolfapi-info-contact-required:
    description: The info object must declare a contact so consumers can reach the provider
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy