Coalition · API Governance Rules

Coalition API Rules

Spectral linting rules defining API design standards and conventions for Coalition.

8 Rules error 1 warn 5 info 2

View Rules File View on GitHub

Rule Categories

coalition

Rules

warn

coalition-ess-operation-summary-title-case

All operation summaries must use Title Case.

$.paths[*][*].summary

warn

coalition-ess-operation-ids-snake-case

ESS API operationIds use snake_case (e.g. cve_cve_get).

$.paths[*][*].operationId

warn

coalition-ess-cve-id-path-param

Single-CVE operations must accept a cve_id path parameter.

$.paths[/cve/{cve_id}*][get].parameters[*]

info

coalition-ess-score-range

ESS / EPSS / CVSS score query parameters must be bounded 0..1 numbers.

$.paths[*][*].parameters[?(@.name=='min_ess_score' || @.name=='max_ess_score' || @.name=='min_epss_score' || @.name=='max_epss_score')]

warn

coalition-ess-pagination-required

List endpoints must expose pagination via page and page_size query parameters.

$.paths[/cve,/cve/{cve_id}/exploits/exploitdb,/cve/{cve_id}/exploits/metasploit,/cve/{cve_id}/mentions/twitter,/cve/{cve_id}/repositories/github,/cve/{cve_id}/history][get]

warn

coalition-ess-public-read-only

ESS API is public read-only; no securitySchemes required, no write methods allowed.

$.paths[*]

error

coalition-ess-server-https

Server URL must use HTTPS.

$.servers[*].url

info

coalition-ess-tags-required

Each operation should have at least one tag for grouping.

$.paths[*][*]

Spectral Ruleset

extends: spectral:oas
rules:
  coalition-ess-operation-summary-title-case:
    description: All operation summaries must use Title Case.
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][A-Za-z0-9]*(\\s[A-Z][A-Za-z0-9]*)*)"

  coalition-ess-operation-ids-snake-case:
    description: ESS API operationIds use snake_case (e.g. cve_cve_get).
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"

  coalition-ess-cve-id-path-param:
    description: Single-CVE operations must accept a cve_id path parameter.
    severity: warn
    given: "$.paths[/cve/{cve_id}*][get].parameters[*]"
    then:
      field: name
      function: enumeration
      functionOptions:
        values:
          - cve_id
          - search
          - page
          - page_size
          - order_by
          - order

  coalition-ess-score-range:
    description: ESS / EPSS / CVSS score query parameters must be bounded 0..1 numbers.
    severity: info
    given: "$.paths[*][*].parameters[?(@.name=='min_ess_score' || @.name=='max_ess_score' || @.name=='min_epss_score' || @.name=='max_epss_score')]"
    then:
      field: schema
      function: truthy

  coalition-ess-pagination-required:
    description: List endpoints must expose pagination via page and page_size query parameters.
    severity: warn
    given: "$.paths[/cve,/cve/{cve_id}/exploits/exploitdb,/cve/{cve_id}/exploits/metasploit,/cve/{cve_id}/mentions/twitter,/cve/{cve_id}/repositories/github,/cve/{cve_id}/history][get]"
    then:
      field: parameters
      function: truthy

  coalition-ess-public-read-only:
    description: ESS API is public read-only; no securitySchemes required, no write methods allowed.
    severity: warn
    given: "$.paths[*]"
    then:
      function: falsy
      field: post

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

  coalition-ess-tags-required:
    description: Each operation should have at least one tag for grouping.
    severity: info
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy