United States Postal Service · API Governance Rules

United States Postal Service API Rules

Spectral linting rules defining API design standards and conventions for United States Postal Service.

72 Rules error 39 warn 22 info 11

Rules by declared severity: the level each rule assigns to a violation. These are not lint results.

Generated by API Evangelist Written by API Evangelist tooling for United States Postal Service's APIs. It is a starting point, not a ruleset United States Postal Service publishes or enforces.
View Rules File View on GitHub

Rule Categories

contact header info mediatype oauthflow operation operationid parameter path property requestbody response schema securityscheme server servers tag write

Rules

error
operation-has-operationid
Every operation declares an operationId (measured: 100% of this contract)
$.paths[*][get,post,put,patch,delete]
warn
operationid-casing-kebab
operationIds are kebab case (measured: 94% of this contract)
$.paths[*][get,post,put,patch,delete].operationId
error
operation-has-summary
Every operation has a summary (measured: 100% of this contract)
$.paths[*][get,post,put,patch,delete]
error
operation-has-description
Every operation has a description (measured: 100% of this contract)
$.paths[*][get,post,put,patch,delete]
error
operation-has-tags
Every operation is tagged (measured: 100% of this contract)
$.paths[*][get,post,put,patch,delete]
warn
operation-has-success-response
Every operation declares a 2xx response (measured: 99% of this contract)
$.paths[*][get,post,put,patch,delete].responses
error
operation-declares-4xx
Every operation declares at least one 4xx response (measured: 100% of this contract)
$.paths[*][get,post,put,patch,delete].responses
info
operation-declares-401-or-403
Every operation declares 401 or 403 (measured: 89% of this contract)
$.paths[*][get,post,put,patch,delete].responses
info
operation-declares-429
Every operation declares 429 (rate limited) (measured: 83% of this contract)
$.paths[*][get,post,put,patch,delete].responses
info
operation-secured
Every operation declares its own security requirement (measured: 89% of this contract)
$.paths[*][get,post,put,patch,delete]
warn
path-segment-casing-kebab
Path segments are kebab case (measured: 98% of this contract)
$.paths[*]~
error
path-no-trailing-slash
Paths carry no trailing slash (measured: 100% of this contract)
$.paths[*]~
error
path-params-in-braces
Path parameters use {braces}, not :colon (measured: 100% of this contract)
$.paths[*]~
error
servers-https
Servers are https (measured: 100% of this contract)
$.servers[*].url
warn
write-declares-request-body
POST and PUT declare a request body (measured: 98% of this contract)
$.paths[*][post,put]
info
response-media-type
Responses are served as application/json (measured: 87% of this contract)
$.paths[*][get,post,put,patch,delete].responses[*].content
info
schema-has-description
Every component schema carries a title or description (measured: 89% of this contract)
$.components.schemas[*]
info
property-name-casing-camel
Schema property names are camel case (measured: 87% of this contract)
$.components.schemas[*].properties[*]~
error
info-has-description
The contract's info block carries a description (measured: 100% of this contract)
$.info
error
info-title-present
Info declares title (measured: 100% of this contract)
$.info
warn
info-title-min-length
Info.title runs at least 7 characters (measured: 97% of this contract)
$.info.title
error
info-description-present
Info declares description (measured: 100% of this contract)
$.info
warn
info-description-min-length
Info.description runs at least 215 characters (measured: 97% of this contract)
$.info.description
error
info-version-present
Info declares version (measured: 100% of this contract)
$.info
error
info-version-semver
info.version is numeric (measured: 100% of this contract)
$.info.version
error
contact-url-https
Contact.url is https (measured: 100% of this contract)
$.info.contact.url
error
server-url-present
Server declares url (measured: 100% of this contract)
$.servers[*]
error
server-url-https
Server.url is https (measured: 100% of this contract)
$.servers[*].url
error
server-description-present
Server declares description (measured: 100% of this contract)
$.servers[*]
warn
server-description-min-length
Server.description runs at least 28 characters (measured: 96% of this contract)
$.servers[*].description
error
tag-name-present
Tag declares name (measured: 100% of this contract)
$.tags[*]
error
tag-description-present
Tag declares description (measured: 100% of this contract)
$.tags[*]
error
operation-tags-present
Operation declares tags (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace]
error
operation-summary-present
Operation declares summary (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace]
warn
operation-summary-min-length
Operation.summary runs at least 22 characters (measured: 96% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].summary
error
operation-description-present
Operation declares description (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace]
warn
operation-description-min-length
Operation.description runs at least 55 characters (measured: 95% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].description
error
operation-operationid-present
Operation declares operationId (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace]
warn
operation-operationid-casing-kebab
Operation.operationId is kebab case (measured: 94% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].operationId
error
operation-responses-present
Operation declares responses (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace]
info
operation-security-present
Operation declares security (measured: 89% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace]
error
parameter-name-present
Parameter declares name (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
error
parameter-in-present
Parameter declares in (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
error
parameter-in-values
Parameter.in is one of header, path, query (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*].in
warn
parameter-description-present
Parameter declares description (measured: 99% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
warn
parameter-description-min-length
Parameter.description runs at least 30 characters (measured: 95% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*].description
warn
parameter-required-present
Parameter declares required (measured: 90% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
error
parameter-style-values
Parameter.style is one of form, simple (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*].style
error
parameter-schema-present
Parameter declares schema (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
error
requestbody-content-present
RequestBody declares content (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].requestBody
warn
mediatype-schema-present
MediaType declares schema (measured: 93% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].content[*]
error
response-description-present
Response declares description (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*]
warn
response-description-min-length
Response.description runs at least 9 characters (measured: 97% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].description
warn
response-content-present
Response declares content (measured: 95% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*]
info
header-description-present
Header declares description (measured: 83% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
info
header-style-present
Header declares style (measured: 80% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
error
header-style-values
Header.style is one of simple (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*].style
info
header-explode-present
Header declares explode (measured: 80% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
error
header-schema-present
Header declares schema (measured: 100% of this contract)
$.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
warn
schema-type-present
Schema declares type (measured: 90% of this contract)
$.components.schemas[*]
warn
schema-type-values
Schema.type is one of array, object, string (measured: 95% of this contract)
$.components.schemas[*].type
info
schema-description-present
Schema declares description (measured: 85% of this contract)
$.components.schemas[*]
warn
schema-description-min-length
Schema.description runs at least 19 characters (measured: 95% of this contract)
$.components.schemas[*].description
warn
schema-format-values
Schema.format is one of date, date-time, double, email (measured: 90% of this contract)
$.components.schemas[*].format
error
securityscheme-type-present
SecurityScheme declares type (measured: 100% of this contract)
$.components.securitySchemes[*]
error
securityscheme-type-values
SecurityScheme.type is one of http, oauth2 (measured: 100% of this contract)
$.components.securitySchemes[*].type
warn
securityscheme-description-present
SecurityScheme declares description (measured: 92% of this contract)
$.components.securitySchemes[*]
error
securityscheme-scheme-values
SecurityScheme.scheme is one of basic, bearer (measured: 100% of this contract)
$.components.securitySchemes[*].scheme
error
securityscheme-bearerformat-values
SecurityScheme.bearerFormat is one of JWT (measured: 100% of this contract)
$.components.securitySchemes[*].bearerFormat
warn
securityscheme-flows-present
SecurityScheme declares flows (measured: 94% of this contract)
$.components.securitySchemes[*]
error
oauthflow-tokenurl-present
OAuthFlow declares tokenUrl (measured: 100% of this contract)
$.components.securitySchemes[*].flows[*]
error
oauthflow-scopes-present
OAuthFlow declares scopes (measured: 100% of this contract)
$.components.securitySchemes[*].flows[*]

Spectral Ruleset

Raw ↑ 
# authorship: generated by API Evangelist tooling (derive-rules.py, 2026-11-11). x-method: generated
# Every rule below was MEASURED against United States Postal Service's own contract before it was written; a rule is present only
# when the contract satisfies it at 80% or more. Severity: 100% -> error, >= 90% -> warn, else info.
# Provenance:
#   - operation-has-operationid: 100%
#   - operationid-casing-kebab: 94%
#   - operation-has-summary: 100%
#   - operation-has-description: 100%
#   - operation-has-tags: 100%
#   - operation-has-success-response: 99%
#   - operation-declares-4xx: 100%
#   - operation-declares-401-or-403: 89%
#   - operation-declares-429: 84%
#   - operation-secured: 89%
#   - path-segment-casing-kebab: 99%
#   - path-no-trailing-slash: 100%
#   - path-params-in-braces: 100%
#   - servers-https: 100%
#   - write-declares-request-body: 99%
#   - response-media-type: 88%
#   - schema-has-description: 90%
#   - property-name-casing-camel: 87%
#   - info-has-description: 100%
#   - info-title-present: 100%
#   - info-title-min-length: 97%
#   - info-description-present: 100%
#   - info-description-min-length: 97%
#   - info-version-present: 100%
#   - info-version-semver: 100%
#   - contact-url-https: 100%
#   - server-url-present: 100%
#   - server-url-https: 100%
#   - server-description-present: 100%
#   - server-description-min-length: 97%
#   - tag-name-present: 100%
#   - tag-description-present: 100%
#   - operation-tags-present: 100%
#   - operation-summary-present: 100%
#   - operation-summary-min-length: 96%
#   - operation-description-present: 100%
#   - operation-description-min-length: 96%
#   - operation-operationid-present: 100%
#   - operation-operationid-casing-kebab: 94%
#   - operation-responses-present: 100%
#   - operation-security-present: 89%
#   - parameter-name-present: 100%
#   - parameter-in-present: 100%
#   - parameter-in-values: 100%
#   - parameter-description-present: 99%
#   - parameter-description-min-length: 95%
#   - parameter-required-present: 90%
#   - parameter-style-values: 100%
#   - parameter-schema-present: 100%
#   - requestbody-content-present: 100%
#   - mediatype-schema-present: 94%
#   - response-description-present: 100%
#   - response-description-min-length: 98%
#   - response-content-present: 95%
#   - header-description-present: 83%
#   - header-style-present: 80%
#   - header-style-values: 100%
#   - header-explode-present: 80%
#   - header-schema-present: 100%
#   - schema-type-present: 91%
#   - schema-type-values: 96%
#   - schema-description-present: 86%
#   - schema-description-min-length: 95%
#   - schema-format-values: 91%
#   - securityscheme-type-present: 100%
#   - securityscheme-type-values: 100%
#   - securityscheme-description-present: 92%
#   - securityscheme-scheme-values: 100%
#   - securityscheme-bearerformat-values: 100%
#   - securityscheme-flows-present: 95%
#   - oauthflow-tokenurl-present: 100%
#   - oauthflow-scopes-present: 100%
x-method: generated
x-generator: derive-rules.py
x-generated: '2026-11-11'
x-source:
- openapi/usps-addresses-openapi.yml
- openapi/usps-adjustments-openapi.yml
- openapi/usps-appointments-openapi.yml
- openapi/usps-carrier-pickup-openapi.yml
- openapi/usps-containers-openapi.yml
x-self-check:
  status: checked
  rules: 72
  dropped: {}
extends:
- - spectral:oas
  - recommended
formats:
- oas3
rules:
  operation-has-operationid:
    description: 'Every operation declares an operationId (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
    x-pattern-key: Operation.operationId|present
  operationid-casing-kebab:
    description: 'operationIds are kebab case (measured: 94% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].operationId
    then:
      function: pattern
      functionOptions:
        match: ^[a-z0-9]+(-[a-z0-9]+)*$
    x-pattern-key: Operation.operationId|pattern:^[a-z0-9]+(-[a-z0-9]+)*$
  operation-has-summary:
    description: 'Every operation has a summary (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy
    x-pattern-key: Operation.summary|present
  operation-has-description:
    description: 'Every operation has a description (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: description
      function: truthy
    x-pattern-key: Operation.description|present
  operation-has-tags:
    description: 'Every operation is tagged (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy
    x-pattern-key: Operation.tags|present
  operation-has-success-response:
    description: 'Every operation declares a 2xx response (measured: 99% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            ^2\d\d$: {}
          minProperties: 1
    x-pattern-key: Operation.responses|schema:07e20b47
  operation-declares-4xx:
    description: 'Every operation declares at least one 4xx response (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            ^4\d\d$: {}
          minProperties: 1
    x-pattern-key: Operation.responses|schema:4aea4da4
  operation-declares-401-or-403:
    description: 'Every operation declares 401 or 403 (measured: 89% of this contract)'
    severity: info
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
          - required:
            - '401'
          - required:
            - '403'
    x-pattern-key: Operation.responses|schema:f26ae517
  operation-declares-429:
    description: 'Every operation declares 429 (rate limited) (measured: 83% of this contract)'
    severity: info
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      field: '429'
      function: truthy
    x-pattern-key: Responses.{key}|present
  operation-secured:
    description: 'Every operation declares its own security requirement (measured: 89% of this contract)'
    severity: info
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: security
      function: truthy
    x-pattern-key: Operation.security|present
  path-segment-casing-kebab:
    description: 'Path segments are kebab case (measured: 98% of this contract)'
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: ^(/[a-z0-9]+(-[a-z0-9]+)*|/\{[^}]+\})+/?$
    x-pattern-key: Paths.{key}|pattern:^(/[a-z0-9]+(-[a-z0-9]+)*|/\{[^}]+\})+/?$
  path-no-trailing-slash:
    description: 'Paths carry no trailing slash (measured: 100% of this contract)'
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: ./$
    x-pattern-key: Paths.{key}|pattern:!./$
  path-params-in-braces:
    description: 'Path parameters use {braces}, not :colon (measured: 100% of this contract)'
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: ':'
    x-pattern-key: 'Paths.{key}|pattern:!:'
  servers-https:
    description: 'Servers are https (measured: 100% of this contract)'
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^(https://|\{)
    x-pattern-key: Server.url|pattern:^(https://|\{)
  write-declares-request-body:
    description: 'POST and PUT declare a request body (measured: 98% of this contract)'
    severity: warn
    given: $.paths[*][post,put]
    then:
      field: requestBody
      function: truthy
    x-pattern-key: Operation.requestBody|present
  response-media-type:
    description: 'Responses are served as application/json (measured: 87% of this contract)'
    severity: info
    given: $.paths[*][get,post,put,patch,delete].responses[*].content
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
          - application/json
    x-pattern-key: Response.content|schema:2919cf38
  schema-has-description:
    description: 'Every component schema carries a title or description (measured: 89% of this contract)'
    severity: info
    given: $.components.schemas[*]
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
          - required:
            - description
          - required:
            - title
    x-pattern-key: Components.schemas|schema:7af42428
  property-name-casing-camel:
    description: 'Schema property names are camel case (measured: 87% of this contract)'
    severity: info
    given: $.components.schemas[*].properties[*]~
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-zA-Z0-9]*$
    x-pattern-key: Schema.properties{key}|pattern:^[a-z][a-zA-Z0-9]*$
  info-has-description:
    description: 'The contract''s info block carries a description (measured: 100% of this contract)'
    severity: error
    given: $.info
    then:
      field: description
      function: truthy
    x-pattern-key: Info.description|present
  info-title-present:
    description: 'Info declares title (measured: 100% of this contract)'
    severity: error
    given: $.info
    then:
      field: title
      function: defined
    x-pattern-key: Info.title|present
  info-title-min-length:
    description: 'Info.title runs at least 7 characters (measured: 97% of this contract)'
    severity: warn
    given: $.info.title
    then:
      function: length
      functionOptions:
        min: 7
    x-pattern-key: Info.title|length
  info-description-present:
    description: 'Info declares description (measured: 100% of this contract)'
    severity: error
    given: $.info
    then:
      field: description
      function: defined
    x-pattern-key: Info.description|present
  info-description-min-length:
    description: 'Info.description runs at least 215 characters (measured: 97% of this contract)'
    severity: warn
    given: $.info.description
    then:
      function: length
      functionOptions:
        min: 215
    x-pattern-key: Info.description|length
  info-version-present:
    description: 'Info declares version (measured: 100% of this contract)'
    severity: error
    given: $.info
    then:
      field: version
      function: defined
    x-pattern-key: Info.version|present
  info-version-semver:
    description: 'info.version is numeric (measured: 100% of this contract)'
    severity: error
    given: $.info.version
    then:
      function: pattern
      functionOptions:
        match: ^v?\d+(\.\d+)*
    x-pattern-key: Info.version|pattern:^v?\d+(\.\d+)*
  contact-url-https:
    description: 'Contact.url is https (measured: 100% of this contract)'
    severity: error
    given: $.info.contact.url
    then:
      function: pattern
      functionOptions:
        match: ^https://
    x-pattern-key: Contact.url|pattern:^https://
  server-url-present:
    description: 'Server declares url (measured: 100% of this contract)'
    severity: error
    given: $.servers[*]
    then:
      field: url
      function: defined
    x-pattern-key: Server.url|present
  server-url-https:
    description: 'Server.url is https (measured: 100% of this contract)'
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^https://
    x-pattern-key: Server.url|pattern:^https://
  server-description-present:
    description: 'Server declares description (measured: 100% of this contract)'
    severity: error
    given: $.servers[*]
    then:
      field: description
      function: defined
    x-pattern-key: Server.description|present
  server-description-min-length:
    description: 'Server.description runs at least 28 characters (measured: 96% of this contract)'
    severity: warn
    given: $.servers[*].description
    then:
      function: length
      functionOptions:
        min: 28
    x-pattern-key: Server.description|length
  tag-name-present:
    description: 'Tag declares name (measured: 100% of this contract)'
    severity: error
    given: $.tags[*]
    then:
      field: name
      function: defined
    x-pattern-key: Tag.name|present
  tag-description-present:
    description: 'Tag declares description (measured: 100% of this contract)'
    severity: error
    given: $.tags[*]
    then:
      field: description
      function: defined
    x-pattern-key: Tag.description|present
  operation-tags-present:
    description: 'Operation declares tags (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace]
    then:
      field: tags
      function: defined
    x-pattern-key: Operation.tags|present
  operation-summary-present:
    description: 'Operation declares summary (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace]
    then:
      field: summary
      function: defined
    x-pattern-key: Operation.summary|present
  operation-summary-min-length:
    description: 'Operation.summary runs at least 22 characters (measured: 96% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].summary
    then:
      function: length
      functionOptions:
        min: 22
    x-pattern-key: Operation.summary|length
  operation-description-present:
    description: 'Operation declares description (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace]
    then:
      field: description
      function: defined
    x-pattern-key: Operation.description|present
  operation-description-min-length:
    description: 'Operation.description runs at least 55 characters (measured: 95% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].description
    then:
      function: length
      functionOptions:
        min: 55
    x-pattern-key: Operation.description|length
  operation-operationid-present:
    description: 'Operation declares operationId (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace]
    then:
      field: operationId
      function: defined
    x-pattern-key: Operation.operationId|present
  operation-operationid-casing-kebab:
    description: 'Operation.operationId is kebab case (measured: 94% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].operationId
    then:
      function: pattern
      functionOptions:
        match: ^[a-z0-9]+(-[a-z0-9]+)*$
    x-pattern-key: Operation.operationId|pattern:^[a-z0-9]+(-[a-z0-9]+)*$
  operation-responses-present:
    description: 'Operation declares responses (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace]
    then:
      field: responses
      function: defined
    x-pattern-key: Operation.responses|present
  operation-security-present:
    description: 'Operation declares security (measured: 89% of this contract)'
    severity: info
    given: $.paths[*][get,put,post,delete,patch,options,head,trace]
    then:
      field: security
      function: defined
    x-pattern-key: Operation.security|present
  parameter-name-present:
    description: 'Parameter declares name (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
    then:
      field: name
      function: defined
    x-pattern-key: Parameter.name|present
  parameter-in-present:
    description: 'Parameter declares in (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
    then:
      field: in
      function: defined
    x-pattern-key: Parameter.in|present
  parameter-in-values:
    description: 'Parameter.in is one of header, path, query (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*].in
    then:
      function: enumeration
      functionOptions:
        values:
        - header
        - path
        - query
    x-pattern-key: Parameter.in|enum:header,path,query
  parameter-description-present:
    description: 'Parameter declares description (measured: 99% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
    then:
      field: description
      function: defined
    x-pattern-key: Parameter.description|present
  parameter-description-min-length:
    description: 'Parameter.description runs at least 30 characters (measured: 95% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*].description
    then:
      function: length
      functionOptions:
        min: 30
    x-pattern-key: Parameter.description|length
  parameter-required-present:
    description: 'Parameter declares required (measured: 90% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
    then:
      field: required
      function: defined
    x-pattern-key: Parameter.required|present
  parameter-style-values:
    description: 'Parameter.style is one of form, simple (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*].style
    then:
      function: enumeration
      functionOptions:
        values:
        - form
        - simple
    x-pattern-key: Parameter.style|enum:form,simple
  parameter-schema-present:
    description: 'Parameter declares schema (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].parameters[*]
    then:
      field: schema
      function: defined
    x-pattern-key: Parameter.schema|present
  requestbody-content-present:
    description: 'RequestBody declares content (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].requestBody
    then:
      field: content
      function: defined
    x-pattern-key: RequestBody.content|present
  mediatype-schema-present:
    description: 'MediaType declares schema (measured: 93% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].content[*]
    then:
      field: schema
      function: defined
    x-pattern-key: MediaType.schema|present
  response-description-present:
    description: 'Response declares description (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*]
    then:
      field: description
      function: defined
    x-pattern-key: Response.description|present
  response-description-min-length:
    description: 'Response.description runs at least 9 characters (measured: 97% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].description
    then:
      function: length
      functionOptions:
        min: 9
    x-pattern-key: Response.description|length
  response-content-present:
    description: 'Response declares content (measured: 95% of this contract)'
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*]
    then:
      field: content
      function: defined
    x-pattern-key: Response.content|present
  header-description-present:
    description: 'Header declares description (measured: 83% of this contract)'
    severity: info
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
    then:
      field: description
      function: defined
    x-pattern-key: Header.description|present
  header-style-present:
    description: 'Header declares style (measured: 80% of this contract)'
    severity: info
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
    then:
      field: style
      function: defined
    x-pattern-key: Header.style|present
  header-style-values:
    description: 'Header.style is one of simple (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*].style
    then:
      function: enumeration
      functionOptions:
        values:
        - simple
    x-pattern-key: Header.style|enum:simple
  header-explode-present:
    description: 'Header declares explode (measured: 80% of this contract)'
    severity: info
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
    then:
      field: explode
      function: defined
    x-pattern-key: Header.explode|present
  header-schema-present:
    description: 'Header declares schema (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][get,put,post,delete,patch,options,head,trace].responses[*].headers[*]
    then:
      field: schema
      function: defined
    x-pattern-key: Header.schema|present
  schema-type-present:
    description: 'Schema declares type (measured: 90% of this contract)'
    severity: warn
    given: $.components.schemas[*]
    then:
      field: type
      function: defined
    x-pattern-key: Schema.type|present
  schema-type-values:
    description: 'Schema.type is one of array, object, string (measured: 95% of this contract)'
    severity: warn
    given: $.components.schemas[*].type
    then:
      function: enumeration
      functionOptions:
        values:
        - array
        - object
        - string
    x-pattern-key: Schema.type|enum:array,object,string
  schema-description-present:
    description: 'Schema declares description (measured: 85% of this contract)'
    severity: info
    given: $.components.schemas[*]
    then:
      field: description
      function: defined
    x-pattern-key: Schema.description|present
  schema-description-min-length:
    description: 'Schema.description runs at least 19 characters (measured: 95% of this contract)'
    severity: warn
    given: $.components.schemas[*].description
    then:
      function: length
      functionOptions:
        min: 19
    x-pattern-key: Schema.description|length
  schema-format-values:
    description: 'Schema.format is one of date, date-time, double, email (measured: 90% of this contract)'
    severity: warn
    given: $.components.schemas[*].format
    then:
      function: enumeration
      functionOptions:
        values:
        - date
        - date-time
        - double
        - email
    x-pattern-key: Schema.format|enum:date,date-time,double,email
  securityscheme-type-present:
    description: 'SecurityScheme declares type (measured: 100% of this contract)'
    severity: error
    given: $.components.securitySchemes[*]
    then:
      field: type
      function: defined
    x-pattern-key: SecurityScheme.type|present
  securityscheme-type-values:
    description: 'SecurityScheme.type is one of http, oauth2 (measured: 100% of this contract)'
    severity: error
    given: $.components.securitySchemes[*].type
    then:
      function: enumeration
      functionOptions:
        values:
        - http
        - oauth2
    x-pattern-key: SecurityScheme.type|enum:http,oauth2
  securityscheme-description-present:
    description: 'SecurityScheme declares description (measured: 92% of this contract)'
    severity: warn
    given: $.components.securitySchemes[*]
    then:
      field: description
      function: defined
    x-pattern-key: SecurityScheme.description|present
  securityscheme-scheme-values:
    description: 'SecurityScheme.scheme is one of basic, bearer (measured: 100% of this contract)'
    severity: error
    given: $.components.securitySchemes[*].scheme
    then:
      function: enumeration
      functionOptions:
        values:
        - basic
        - bearer
    x-pattern-key: SecurityScheme.scheme|enum:basic,bearer
  securityscheme-bearerformat-values:
    description: 'SecurityScheme.bearerFormat is one of JWT (measured: 100% of this contract)'
    severity: error
    given: $.components.securitySchemes[*].bearerFormat
    then:
      function: enumeration
      functionOptions:
        values:
        - JWT
    x-pattern-key: SecurityScheme.bearerFormat|enum:JWT
  securityscheme-flows-present:
    description: 'SecurityScheme declares flows (measured: 94% of this contract)'
    severity: warn
    given: $.components.securitySchemes[*]
    then:
      field: flows
      function: defined
    x-pattern-key: SecurityScheme.flows|present
  oauthflow-tokenurl-present:
    description: 'OAuthFlow declares tokenUrl (measured: 100% of this contract)'
    severity: error
    given: $.components.securitySchemes[*].flows[*]
    then:
      field: tokenUrl
      function: defined
    x-pattern-key: OAuthFlow.tokenUrl|present
  oauthflow-scopes-present:
    description: 'OAuthFlow declares scopes (measured: 100% of this contract)'
    severity: error
    given: $.components.securitySchemes[*].flows[*]
    then:
      field: scopes
      function: defined
    x-pattern-key: OAuthFlow.scopes|present

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/usps-rules"
All spectral rules 
curl "https://apis.io/api/v1/rules?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

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.