ThingsBoard · API Governance Rules

ThingsBoard API Rules

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

6 Rules error 2 warn 4

View Rules File View on GitHub

Rule Categories

bearer components operation thingsboard use

Rules

warn

operation-summary-title-case

Operation summaries should use Title Case (ThingsBoard convention).

$.paths[*][get,post,put,delete,patch].summary

error

operation-tag-required

Every operation must declare at least one tag (controller).

$.paths[*][get,post,put,delete,patch]

error

thingsboard-path-prefix

All ThingsBoard REST endpoints must live under /api/.

$.paths

warn

use-uuid-for-ids

Path parameters named *Id should be UUID format.

$.paths[*][*].parameters[?(@.name && @.name.match(/Id$/))].schema

warn

components-schemas-named

Component schemas must use PascalCase.

$.components.schemas

warn

bearer-or-apikey-security

Operations should require bearerAuth or apiKeyAuth (excluding the login endpoint).

$.paths[?([email protected]('/auth/login'))][*].security

Spectral Ruleset

extends: spectral:oas
rules:
  operation-summary-title-case:
    description: Operation summaries should use Title Case (ThingsBoard convention).
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].summary
    then:
      function: pattern
      functionOptions:
        match: '^([A-Z][a-z0-9]*)(\s+(of|the|a|an|and|or|for|to|in|on|by|with|as|at|from|is|[A-Z][a-zA-Z0-9]*))*$'

  operation-tag-required:
    description: Every operation must declare at least one tag (controller).
    severity: error
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: tags
      function: truthy

  thingsboard-path-prefix:
    description: All ThingsBoard REST endpoints must live under /api/.
    severity: error
    given: $.paths
    then:
      function: pattern
      functionOptions:
        match: '^/api(/.*)?$'

  use-uuid-for-ids:
    description: Path parameters named *Id should be UUID format.
    severity: warn
    given: $.paths[*][*].parameters[?(@.name && @.name.match(/Id$/))].schema
    then:
      field: format
      function: enumeration
      functionOptions:
        values: [uuid]

  components-schemas-named:
    description: Component schemas must use PascalCase.
    severity: warn
    given: $.components.schemas
    then:
      field: '@key'
      function: pattern
      functionOptions:
        match: '^[A-Z][a-zA-Z0-9]+$'

  bearer-or-apikey-security:
    description: Operations should require bearerAuth or apiKeyAuth (excluding the login endpoint).
    severity: warn
    given: "$.paths[?([email protected]('/auth/login'))][*].security"
    then:
      function: truthy