S&P Global · API Governance Rules

S&P Global API Rules

Spectral linting rules defining API design standards and conventions for S&P Global.

S&P Global API Rules is a Spectral governance ruleset published by S&P Global on the APIs.io network, containing 12 lint rules.

The ruleset includes 5 error-severity rules and 7 warning-severity rules.

Tagged areas include Capital IQ, Commodity Insights, Credit Ratings, Document Extraction, and ESG.

Rulesets can be applied to your own OpenAPI specs via Spectral to enforce the same governance standards.

12 Rules error 5 warn 7

View Rules File View on GitHub

Rule Categories

spg

Rules

error

spg-info-title-required

Every S&P Global OpenAPI spec must declare an info.title.

$.info

error

spg-info-version-required

Every S&P Global OpenAPI spec must declare an info.version.

$.info

error

spg-servers-https-only

All Kensho service servers must use HTTPS (e.g., https://kfinance.kensho.com).

$.servers[*].url

warn

spg-server-kensho-domain

Kensho service base URLs should resolve to a *.kensho.com host.

$.servers[*].url

warn

spg-path-segments-snake-case

Path segments use snake_case lowercase per the LLM-ready API convention.

$.paths.*~

warn

spg-versioned-path

All non-metadata paths are versioned (e.g., /api/v1/... or /v3/...).

$.paths.*~

warn

spg-operation-summary-title-case

Operation summaries should use Title Case (first letter of each significant word capitalised).

$.paths.*.*.summary

warn

spg-operation-id-required

Every operation must declare an operationId for SDK/codegen stability.

$.paths.*.*

error

spg-success-response-defined

Every operation must define at least one 2xx response.

$.paths.*.*.responses

warn

spg-security-required

S&P Global APIs require authenticated access (OIDC bearer or keypair JWT).

warn

spg-extract-versioned-v3

Kensho Extract paths must be under /v3 (current GA major).

$.paths.*~

error

spg-no-stage-in-host

Production servers must not embed dev/staging/qa/test in the host.

$.servers[*].url

Spectral Ruleset

extends:
  - spectral:oas
formats:
  - oas3

functions: []

rules:
  spg-info-title-required:
    description: Every S&P Global OpenAPI spec must declare an info.title.
    message: '{{property}} is required.'
    given: $.info
    severity: error
    then:
      field: title
      function: truthy

  spg-info-version-required:
    description: Every S&P Global OpenAPI spec must declare an info.version.
    given: $.info
    severity: error
    then:
      field: version
      function: truthy

  spg-servers-https-only:
    description: All Kensho service servers must use HTTPS (e.g., https://kfinance.kensho.com).
    given: $.servers[*].url
    severity: error
    then:
      function: pattern
      functionOptions:
        match: '^https://'

  spg-server-kensho-domain:
    description: Kensho service base URLs should resolve to a *.kensho.com host.
    given: $.servers[*].url
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: '\.kensho\.com(/|$)'

  spg-path-segments-snake-case:
    description: Path segments use snake_case lowercase per the LLM-ready API convention.
    given: $.paths.*~
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: '^/(api/v[0-9]+/|v[0-9]+/|me$|me/)?[a-z0-9_/{}.-]+$'

  spg-versioned-path:
    description: All non-metadata paths are versioned (e.g., /api/v1/... or /v3/...).
    given: $.paths.*~
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: '^/(api/v[0-9]+|v[0-9]+|me)'

  spg-operation-summary-title-case:
    description: Operation summaries should use Title Case (first letter of each significant word capitalised).
    given: $.paths.*.*.summary
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z]'

  spg-operation-id-required:
    description: Every operation must declare an operationId for SDK/codegen stability.
    given: $.paths.*.*
    severity: warn
    then:
      field: operationId
      function: truthy

  spg-success-response-defined:
    description: Every operation must define at least one 2xx response.
    given: $.paths.*.*.responses
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            '^2[0-9]{2}$': true
          minProperties: 1

  spg-security-required:
    description: S&P Global APIs require authenticated access (OIDC bearer or keypair JWT).
    given: $
    severity: warn
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            security:
              type: array
              minItems: 1
            components:
              type: object
              properties:
                securitySchemes:
                  type: object
                  minProperties: 1

  spg-extract-versioned-v3:
    description: Kensho Extract paths must be under /v3 (current GA major).
    given: $.paths.*~
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: '^(/v3/|$)'
    when:
      field: $.info.title
      pattern: 'Kensho Extract'

  spg-no-stage-in-host:
    description: Production servers must not embed dev/staging/qa/test in the host.
    given: $.servers[*].url
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: '(dev|staging|stage|qa|test|preview)\.'