The Color API · API Governance Rules

The Color API API Rules

Spectral linting rules defining API design standards and conventions for The Color API.

10 Rules error 4 warn 6

View Rules File View on GitHub

Rule Categories

colorapi

Rules

warn

colorapi-operations-must-have-tags

All Color API operations must be tagged (Colors or Schemes).

$.paths[*][get]

error

colorapi-operations-must-have-operationid

All operations must define an operationId.

$.paths[*][get]

warn

colorapi-operations-must-have-summary

All operations must have a summary in Title Case.

$.paths[*][get]

warn

colorapi-color-input-params-must-have-examples

Color input parameters (hex, rgb, hsl, cmyk) should include examples.

$.paths[*][get].parameters[?(@.name == 'hex' || @.name == 'rgb' || @.name == 'hsl' || @.name == 'cmyk')]

error

colorapi-format-param-must-use-enum

The format parameter must constrain values to json, html, or svg.

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

error

colorapi-scheme-mode-must-use-enum

The mode parameter must constrain values to the supported scheme modes.

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

error

colorapi-responses-must-include-200

All operations must define a 200 success response.

$.paths[*][get].responses

warn

colorapi-responses-must-include-400

All operations must define a 400 error response for invalid color input.

$.paths[*][get].responses

warn

colorapi-parameters-must-have-descriptions

All query parameters must have descriptions.

$.paths[*][get].parameters[*]

warn

colorapi-responses-must-define-content-schema

All 200 responses must reference a schema.

$.paths[*][get].responses.200.content.application/json

Spectral Ruleset

extends: spectral:oas
rules:
  colorapi-operations-must-have-tags:
    description: All Color API operations must be tagged (Colors or Schemes).
    severity: warn
    given: "$.paths[*][get]"
    then:
      field: tags
      function: truthy

  colorapi-operations-must-have-operationid:
    description: All operations must define an operationId.
    severity: error
    given: "$.paths[*][get]"
    then:
      field: operationId
      function: truthy

  colorapi-operations-must-have-summary:
    description: All operations must have a summary in Title Case.
    severity: warn
    given: "$.paths[*][get]"
    then:
      field: summary
      function: truthy

  colorapi-color-input-params-must-have-examples:
    description: Color input parameters (hex, rgb, hsl, cmyk) should include examples.
    severity: warn
    given: "$.paths[*][get].parameters[?(@.name == 'hex' || @.name == 'rgb' || @.name == 'hsl' || @.name == 'cmyk')]"
    then:
      field: example
      function: truthy

  colorapi-format-param-must-use-enum:
    description: The format parameter must constrain values to json, html, or svg.
    severity: error
    given: "$.paths[*][get].parameters[?(@.name == 'format')].schema"
    then:
      field: enum
      function: truthy

  colorapi-scheme-mode-must-use-enum:
    description: The mode parameter must constrain values to the supported scheme modes.
    severity: error
    given: "$.paths[*][get].parameters[?(@.name == 'mode')].schema"
    then:
      field: enum
      function: truthy

  colorapi-responses-must-include-200:
    description: All operations must define a 200 success response.
    severity: error
    given: "$.paths[*][get].responses"
    then:
      field: "200"
      function: truthy

  colorapi-responses-must-include-400:
    description: All operations must define a 400 error response for invalid color input.
    severity: warn
    given: "$.paths[*][get].responses"
    then:
      field: "400"
      function: truthy

  colorapi-parameters-must-have-descriptions:
    description: All query parameters must have descriptions.
    severity: warn
    given: "$.paths[*][get].parameters[*]"
    then:
      field: description
      function: truthy

  colorapi-responses-must-define-content-schema:
    description: All 200 responses must reference a schema.
    severity: warn
    given: "$.paths[*][get].responses.200.content.application/json"
    then:
      field: schema
      function: truthy