Knock · API Governance Rules

Knock API Rules

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

8 Rules error 3 warn 3 info 2
View Rules File View on GitHub

Rule Categories

knock

Rules

error
knock-server-base-url
Knock OpenAPI specs MUST list either api.knock.app or control.knock.app as a server.
$.servers[*].url
error
knock-bearer-auth
Knock APIs MUST require bearer-token authentication.
$.components.securitySchemes[*]
error
knock-paths-v1-prefix
All Knock API paths MUST be under /v1/.
$.paths
warn
knock-operation-summary-required
Every operation should have a summary.
$.paths.*[get,post,put,patch,delete]
warn
knock-snake-case-properties
Knock JSON property names are snake_case.
$.components.schemas..properties.*~
warn
knock-pagination-cursor
List endpoints should support cursor pagination (before/after) over offset.
$.paths.*.get.parameters[?(@.name=='page' || @.name=='offset')]
info
knock-rate-limit-headers-documented
429 responses should document rate-limit retry behavior.
$.paths.*.*.responses['429']
info
knock-idempotency-key-header
POST endpoints SHOULD accept an Idempotency-Key header.
$.paths.*.post.parameters[*].name

Spectral Ruleset

Raw ↑ 
extends: [[spectral:oas, all]]
documentationUrl: https://docs.knock.app/api-reference/overview
functions: []
rules:
  knock-server-base-url:
    description: Knock OpenAPI specs MUST list either api.knock.app or control.knock.app as a server.
    message: 'Knock specs must use api.knock.app (runtime API) or control.knock.app (Management API) as a server.'
    severity: error
    given: '$.servers[*].url'
    then:
      function: pattern
      functionOptions:
        match: '^https://(api|control)\.knock\.app$'

  knock-bearer-auth:
    description: Knock APIs MUST require bearer-token authentication.
    severity: error
    given: '$.components.securitySchemes[*]'
    then:
      - field: type
        function: enumeration
        functionOptions:
          values: [http]
      - field: scheme
        function: enumeration
        functionOptions:
          values: [bearer]

  knock-paths-v1-prefix:
    description: All Knock API paths MUST be under /v1/.
    severity: error
    given: '$.paths'
    then:
      field: '@key'
      function: pattern
      functionOptions:
        match: '^/v1/'

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

  knock-snake-case-properties:
    description: Knock JSON property names are snake_case.
    severity: warn
    given: '$.components.schemas..properties.*~'
    then:
      function: pattern
      functionOptions:
        match: '^[a-z][a-z0-9_]*$'

  knock-pagination-cursor:
    description: List endpoints should support cursor pagination (before/after) over offset.
    severity: warn
    given: "$.paths.*.get.parameters[?(@.name=='page' || @.name=='offset')]"
    then:
      function: falsy

  knock-rate-limit-headers-documented:
    description: 429 responses should document rate-limit retry behavior.
    severity: info
    given: "$.paths.*.*.responses['429']"
    then:
      field: description
      function: truthy

  knock-idempotency-key-header:
    description: POST endpoints SHOULD accept an Idempotency-Key header.
    severity: info
    given: '$.paths.*.post.parameters[*].name'
    then:
      function: undefined