Common Sense Media API Rules

extends:
  - spectral:oas

# Spectral linting rules for the Common Sense Media Reviews API (v3).
# Tuned to api.commonsense.org conventions: x-api-key header, GET-only
# review browsing, and UUID-keyed entities.
rules:
  csm-info-contact:
    description: API info must include a contact block.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  csm-server-https:
    description: Server URLs must use HTTPS.
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  csm-server-host:
    description: Server URL should point to api.commonsense.org.
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "api\\.commonsense\\.org"

  csm-version-prefix:
    description: Server URL should include the /api/v3 path prefix.
    severity: info
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "/api/v3"

  csm-operation-id:
    description: Every operation must declare a unique operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  csm-operation-tags:
    description: Operations must declare at least one tag.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  csm-only-get:
    description: Common Sense Media v3 only supports GET methods.
    severity: warn
    given: "$.paths[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          not:
            anyOf:
              - required: [post]
              - required: [put]
              - required: [patch]
              - required: [delete]

  csm-api-key-security:
    description: API key security scheme must be declared.
    severity: error
    given: "$.components.securitySchemes"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            ApiKey:
              type: object
              properties:
                type:
                  const: apiKey
                in:
                  const: header
                name:
                  const: X-Api-Key

  csm-uuid-paths:
    description: Item-scoped paths should be keyed by a UUID parameter.
    severity: info
    given: "$.paths[?(@property.indexOf('reviewId') > -1)]"
    then:
      function: pattern
      functionOptions:
        match: "{reviewId}"