U.S. Geological Survey · API Governance Rules

U.S. Geological Survey — usgs rules

Spectral linting rules defining API design standards and conventions for U.S. Geological Survey.

33 Rules error 9 warn 14 info 10
Authorship not recorded No authorship marker is recorded for this file. It is not presented as the provider's; it was most likely written by an API Evangelist pass before outputs were stamped.
View Rules File View on GitHub

Rule Categories

get info no openapi operation parameter paths response schema security servers tags usgs

Rules

error
info-title-required
API title must be present and include "USGS".
$.info.title
warn
info-description-min-length
API description must be at least 50 characters.
$.info
error
info-version-required
API version must be specified.
$.info
warn
info-contact-required
Contact information should be present.
$.info
info
info-license-required
License information should be present for government APIs.
$.info
warn
openapi-version-3
USGS API specs must use OpenAPI 3.0.x.
$
error
servers-defined
At least one server URL must be defined.
$
error
servers-https
All server URLs must use HTTPS.
$.servers[*].url
info
servers-usgs-domain
Server URLs should reference usgs.gov domains.
$.servers[*].url
warn
paths-kebab-case
Path segments must use kebab-case.
$.paths[*]~
info
paths-no-trailing-slash
Paths should not end with a trailing slash (except root).
$.paths[*]~
error
operation-summary-required
All operations must have a summary.
$.paths[*][get,post,put,patch,delete]
warn
operation-summary-prefix
Operation summaries should start with "USGS".
$.paths[*][get,post,put,patch,delete].summary
warn
operation-description-required
All operations should have a description.
$.paths[*][get,post,put,patch,delete]
error
operation-id-required
All operations must have an operationId.
$.paths[*][get,post,put,patch,delete]
warn
operation-id-camel-case
OperationIds should use camelCase.
$.paths[*][get,post,put,patch,delete].operationId
warn
operation-tags-required
All operations must have at least one tag.
$.paths[*][get,post,put,patch,delete]
info
tags-global-defined
Global tags array should be defined with descriptions.
$
warn
parameter-description-required
All parameters must have a description.
$.paths[*][get,post,put,patch,delete].parameters[*]
error
parameter-schema-required
All parameters must define a schema.
$.paths[*][get,post,put,patch,delete].parameters[*]
info
parameter-format-lowercase
Format parameter values should use lowercase identifiers.
$.paths[*][get,post,put,patch,delete].parameters[?(@.name == 'f')].schema.enum[*]
error
response-success-required
All operations must define a 200 success response.
$.paths[*][get,post,put,patch,delete].responses
warn
response-400-defined
Operations should define a 400 error response.
$.paths[*][get,post,put,patch,delete].responses
info
response-403-defined
Authenticated operations should define a 403 error response.
$.paths[*][get,post].responses
warn
response-description-required
All response definitions must have descriptions.
$.paths[*][get,post,put,patch,delete].responses[*]
warn
schema-description-required
Component schemas should have descriptions.
$.components.schemas[*]
info
schema-geojson-type-documented
GeoJSON Feature and FeatureCollection schemas should document the 'type' property.
$.components.schemas[?(@.title =~ /Feature|Collection/)].properties
warn
security-scheme-defined
API key security schemes should be defined in components.
$.components.securitySchemes
info
security-api-key-documented
API key security scheme should describe how to obtain the key.
$.components.securitySchemes[*]
error
get-no-request-body
GET operations must not have a request body.
$.paths[*].get
info
usgs-ogc-format-parameter
OGC API endpoints should support the 'f' format parameter.
$.paths[*].get.parameters[*].name
info
usgs-rate-limit-documented
APIs with API key auth should document 429 responses.
$.paths[*][get,post].responses
warn
no-empty-descriptions
Descriptions should not be empty.
$..description

Spectral Ruleset

Raw ↑ 
rules:
  # INFO / METADATA
  info-title-required:
    description: API title must be present and include "USGS".
    severity: error
    given: $.info.title
    then:
      function: truthy

  info-description-min-length:
    description: API description must be at least 50 characters.
    severity: warn
    given: $.info
    then:
      field: description
      function: minLength
      functionOptions:
        min: 50

  info-version-required:
    description: API version must be specified.
    severity: error
    given: $.info
    then:
      field: version
      function: truthy

  info-contact-required:
    description: Contact information should be present.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy

  info-license-required:
    description: License information should be present for government APIs.
    severity: info
    given: $.info
    then:
      field: license
      function: truthy

  # OPENAPI VERSION
  openapi-version-3:
    description: USGS API specs must use OpenAPI 3.0.x.
    severity: warn
    given: $
    then:
      field: openapi
      function: pattern
      functionOptions:
        match: "^3\\.0\\."

  # SERVERS
  servers-defined:
    description: At least one server URL must be defined.
    severity: error
    given: $
    then:
      field: servers
      function: truthy

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

  servers-usgs-domain:
    description: Server URLs should reference usgs.gov domains.
    severity: info
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "usgs\\.gov"

  # PATHS — NAMING CONVENTIONS
  paths-kebab-case:
    description: Path segments must use kebab-case.
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}_.-]*)+$"

  paths-no-trailing-slash:
    description: Paths should not end with a trailing slash (except root).
    severity: info
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: ".+/$"

  # OPERATIONS
  operation-summary-required:
    description: All operations must have a summary.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy

  operation-summary-prefix:
    description: Operation summaries should start with "USGS".
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].summary
    then:
      function: pattern
      functionOptions:
        match: "^USGS"

  operation-description-required:
    description: All operations should have a description.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: description
      function: truthy

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

  operation-id-camel-case:
    description: OperationIds should use camelCase.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].operationId
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  operation-tags-required:
    description: All operations must have at least one tag.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy

  # TAGS
  tags-global-defined:
    description: Global tags array should be defined with descriptions.
    severity: info
    given: $
    then:
      field: tags
      function: truthy

  # PARAMETERS
  parameter-description-required:
    description: All parameters must have a description.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[*]
    then:
      field: description
      function: truthy

  parameter-schema-required:
    description: All parameters must define a schema.
    severity: error
    given: $.paths[*][get,post,put,patch,delete].parameters[*]
    then:
      field: schema
      function: truthy

  parameter-format-lowercase:
    description: Format parameter values should use lowercase identifiers.
    severity: info
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.name == 'f')].schema.enum[*]
    then:
      function: pattern
      functionOptions:
        match: "^[a-z]+$"

  # RESPONSES
  response-success-required:
    description: All operations must define a 200 success response.
    severity: error
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - "200"

  response-400-defined:
    description: Operations should define a 400 error response.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - "400"

  response-403-defined:
    description: Authenticated operations should define a 403 error response.
    severity: info
    given: $.paths[*][get,post].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - "403"

  response-description-required:
    description: All response definitions must have descriptions.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses[*]
    then:
      field: description
      function: truthy

  # SCHEMAS — PROPERTY NAMING
  schema-description-required:
    description: Component schemas should have descriptions.
    severity: warn
    given: $.components.schemas[*]
    then:
      field: description
      function: truthy

  schema-geojson-type-documented:
    description: GeoJSON Feature and FeatureCollection schemas should document the 'type' property.
    severity: info
    given: $.components.schemas[?(@.title =~ /Feature|Collection/)].properties
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - type

  # SECURITY
  security-scheme-defined:
    description: API key security schemes should be defined in components.
    severity: warn
    given: $.components.securitySchemes
    then:
      function: truthy

  security-api-key-documented:
    description: API key security scheme should describe how to obtain the key.
    severity: info
    given: $.components.securitySchemes[*]
    then:
      field: description
      function: truthy

  # HTTP METHOD CONVENTIONS
  get-no-request-body:
    description: GET operations must not have a request body.
    severity: error
    given: $.paths[*].get
    then:
      field: requestBody
      function: falsy

  # OGC/USGS SPECIFIC
  usgs-ogc-format-parameter:
    description: OGC API endpoints should support the 'f' format parameter.
    severity: info
    given: $.paths[*].get.parameters[*].name
    then:
      function: schema
      functionOptions:
        schema:
          type: string

  usgs-rate-limit-documented:
    description: APIs with API key auth should document 429 responses.
    severity: info
    given: $.paths[*][get,post].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - "429"

  # GENERAL QUALITY
  no-empty-descriptions:
    description: Descriptions should not be empty.
    severity: warn
    given: $..description
    then:
      function: pattern
      functionOptions:
        match: ".{1,}"

Work with this as data

Every ruleset here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for spectral rules

4 MCP tools reach this
  • find_rulesBrowse and filter every ruleset in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This ruleset 
curl "https://apis.io/api/v1/rules/usgs-spectral-rules"
All spectral rules 
curl "https://apis.io/api/v1/rules?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.