Social Security Administration · API Governance Rules

Social Security Administration API Rules

Spectral linting rules defining API design standards and conventions for Social Security Administration.

8 Rules error 4 warn 3 info 1

View Rules File View on GitHub

Rule Categories

ssa

Rules

info

ssa-no-authentication

SSA public data APIs do not require authentication

$.security

error

ssa-arcgis-query-where-required

ArcGIS query endpoints should document the required where parameter

$.paths.*.get.parameters[?(@.name == 'where')]

warn

ssa-arcgis-format-parameter

ArcGIS endpoints should document the f (format) parameter

$.paths.*.*.parameters

error

ssa-government-license-documented

Government APIs must document public domain licensing

$.info.license

error

ssa-contact-info-required

Government APIs must provide contact information

$.info.contact

error

ssa-tags-required

All operations must have tags

$.paths.*.*

warn

ssa-response-schema-defined

Responses should define a schema for data consumers

$.paths.*.*.responses.*.content.*.schema

warn

ssa-path-kebab-case

URL path segments should use kebab-case

$.paths

Spectral Ruleset

extends: spectral:oas
rules:
  ssa-no-authentication:
    description: SSA public data APIs do not require authentication
    message: "SSA public location APIs should not require authentication — they serve public government data."
    severity: info
    given: "$.security"
    then:
      function: falsy

  ssa-arcgis-query-where-required:
    description: ArcGIS query endpoints should document the required where parameter
    message: "ArcGIS query endpoints must document the 'where' parameter for SQL filtering."
    severity: error
    given: "$.paths.*.get.parameters[?(@.name == 'where')]"
    then:
      field: required
      function: truthy

  ssa-arcgis-format-parameter:
    description: ArcGIS endpoints should document the f (format) parameter
    message: "ArcGIS REST endpoints should document the 'f' parameter for response format selection."
    severity: warn
    given: "$.paths.*.*.parameters"
    then:
      function: truthy

  ssa-government-license-documented:
    description: Government APIs must document public domain licensing
    message: "Government APIs must document their license as public domain or U.S. Government Work."
    severity: error
    given: "$.info.license"
    then:
      field: name
      function: truthy

  ssa-contact-info-required:
    description: Government APIs must provide contact information
    message: "Government API specifications must include contact information for the agency."
    severity: error
    given: "$.info.contact"
    then:
      field: url
      function: truthy

  ssa-tags-required:
    description: All operations must have tags
    message: "All SSA API operations must include descriptive tags."
    severity: error
    given: "$.paths.*.*"
    then:
      field: tags
      function: truthy

  ssa-response-schema-defined:
    description: Responses should define a schema for data consumers
    message: "API responses should define a schema to help developers understand the data structure."
    severity: warn
    given: "$.paths.*.*.responses.*.content.*.schema"
    then:
      function: truthy

  ssa-path-kebab-case:
    description: URL path segments should use kebab-case
    message: "Path segments should use kebab-case (lowercase with hyphens)."
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}-]+)*/?$"