Superhero API (akabab) API Rules

extends:
  - "spectral:oas"
rules:
  # API surface conventions for the akabab/superhero-api static REST API.

  superheroes-operation-id-required:
    description: Every operation MUST have an operationId.
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: error
    then:
      field: operationId
      function: truthy

  superheroes-operation-id-camelcase:
    description: operationId MUST be camelCase.
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  superheroes-operation-summary-title-case:
    description: Operation summaries SHOULD be Title Case.
    given: "$.paths[*][get,post,put,patch,delete].summary"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][a-zA-Z0-9]*)(\\s+[A-Z][a-zA-Z0-9]*)*$"

  superheroes-get-only:
    description: The static API is read-only — only GET methods are allowed.
    given: "$.paths[*]"
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          additionalProperties: true
          not:
            anyOf:
              - required: [post]
              - required: [put]
              - required: [patch]
              - required: [delete]

  superheroes-json-extension-on-data-paths:
    description: Data endpoints MUST end in `.json` (static file convention).
    given: "$.paths"
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            "^/(all|id|powerstats|appearance|biography|work|connections)":
              type: object
          additionalProperties: true

  superheroes-character-id-range:
    description: The CharacterId parameter MUST constrain id to 1..731.
    given: "$.components.parameters.CharacterId.schema"
    severity: warn
    then:
      - field: minimum
        function: truthy
      - field: maximum
        function: truthy

  superheroes-image-size-enum:
    description: Image size path parameter MUST be one of xs, sm, md, lg.
    given: "$.paths['/images/{size}/{filename}'].get.parameters[?(@.name=='size')].schema"
    severity: error
    then:
      field: enum
      function: truthy

  superheroes-license-required:
    description: The info.license block MUST be present (project is MIT-licensed).
    given: "$.info"
    severity: error
    then:
      field: license
      function: truthy

  superheroes-servers-include-cdn:
    description: The servers array SHOULD include the jsDelivr CDN mirror.
    given: "$.servers[*].url"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "(akabab\\.github\\.io|cdn\\.jsdelivr\\.net)"