Holiday API · API Governance Rules

Holiday API API Rules

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

16 Rules error 9 warn 7
View Rules File View on GitHub

Rule Categories

api components format info operation paths response servers

Rules

error
info-title-required
Info title must be present
$.info
error
info-description-required
Info description must be present
$.info
warn
info-contact-required
Info contact block must be present
$.info
warn
info-termsOfService-required
Info termsOfService URL must be present
$.info
error
operation-operationid-required
Every operation must have an operationId
$.paths[*][get,post,put,patch,delete]
error
operation-summary-required
Every operation must have a summary
$.paths[*][get,post,put,patch,delete]
warn
operation-summary-title-case
Operation summaries should use Title Case (Holiday API convention)
$.paths[*][get,post,put,patch,delete].summary
error
operation-tags-required
Every operation must have at least one tag
$.paths[*][get,post,put,patch,delete]
warn
operation-description-required
Every operation should have a description
$.paths[*][get,post,put,patch,delete]
error
api-key-query-param-required
Holiday API operations must accept a 'key' query parameter (per provider auth convention)
$.paths[*][get,post,put,patch,delete].parameters[?(@.name=='key')]
error
api-key-required-true
The 'key' parameter must be required
$.paths[*][get,post,put,patch,delete].parameters[?(@.name=='key')]
error
paths-must-be-versioned
All paths must be prefixed with /v1 (Holiday API versioning convention)
$.paths
error
servers-defined
Top-level servers must be defined
$
warn
components-schemas-defined
Reusable schemas must live under components.schemas
$.components
warn
response-schema-required
2xx responses must reference a schema
$.paths[*][get,post,put,patch,delete].responses['200'].content['application/json']
warn
format-param-enum-consistent
When present, format parameter must enumerate the supported response formats
$.paths[*][get,post,put,patch,delete].parameters[?(@.name=='format')]

Spectral Ruleset

Raw ↑ 
extends:
  - spectral:oas
rules:
  info-title-required:
    description: Info title must be present
    severity: error
    given: $.info
    then: {field: title, function: truthy}
  info-description-required:
    description: Info description must be present
    severity: error
    given: $.info
    then: {field: description, function: truthy}
  info-contact-required:
    description: Info contact block must be present
    severity: warn
    given: $.info
    then: {field: contact, function: truthy}
  info-termsOfService-required:
    description: Info termsOfService URL must be present
    severity: warn
    given: $.info
    then: {field: termsOfService, function: truthy}
  operation-operationid-required:
    description: Every operation must have an operationId
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then: {field: operationId, function: truthy}
  operation-summary-required:
    description: Every operation must have a summary
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then: {field: summary, function: truthy}
  operation-summary-title-case:
    description: Operation summaries should use Title Case (Holiday API convention)
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].summary
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][a-z0-9'/-]*)(\\s+([A-Za-z0-9'/-]+))*$"
  operation-tags-required:
    description: Every operation must have at least one tag
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then: {field: tags, function: truthy}
  operation-description-required:
    description: Every operation should have a description
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then: {field: description, function: truthy}
  api-key-query-param-required:
    description: Holiday API operations must accept a 'key' query parameter (per provider auth convention)
    severity: error
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.name=='key')]
    then:
      field: in
      function: pattern
      functionOptions:
        match: "^query$"
  api-key-required-true:
    description: The 'key' parameter must be required
    severity: error
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.name=='key')]
    then: {field: required, function: truthy}
  paths-must-be-versioned:
    description: All paths must be prefixed with /v1 (Holiday API versioning convention)
    severity: error
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^/v1/"
  servers-defined:
    description: Top-level servers must be defined
    severity: error
    given: $
    then: {field: servers, function: truthy}
  components-schemas-defined:
    description: Reusable schemas must live under components.schemas
    severity: warn
    given: $.components
    then: {field: schemas, function: truthy}
  response-schema-required:
    description: 2xx responses must reference a schema
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses['200'].content['application/json']
    then: {field: schema, function: truthy}
  format-param-enum-consistent:
    description: When present, format parameter must enumerate the supported response formats
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.name=='format')]
    then:
      field: schema.enum
      function: truthy