TetraScience · API Governance Rules

TetraScience API Rules

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

14 Rules error 6 warn 6 info 2
View Rules File View on GitHub

Rule Categories

operation tetra

Rules

error
operation-tag-defined
Every operation must declare at least one tag for navigation
$.paths[*][get,post,put,delete,patch]
error
operation-summary-required
Every operation must have a summary
$.paths[*][get,post,put,delete,patch]
warn
operation-summary-title-case
Operation summaries should start with a capital letter
$.paths[*][get,post,put,delete,patch].summary
warn
operation-description-required
Operations should include a description
$.paths[*][get,post,put,delete,patch]
warn
tetra-path-no-uppercase-segments
Path segments should not be ALL CAPS
$.paths
error
tetra-secure-v1
All /v1 operations must require authentication
$.paths[?(@property.startsWith('/v1'))][get,post,put,delete,patch]
error
tetra-auth-token-defined
The ts-auth-token apiKey security scheme must be defined
$.components.securitySchemes
error
tetra-org-slug-defined
The x-org-slug apiKey security scheme must be defined for tenant routing
$.components.securitySchemes
error
tetra-production-server
The production server URL https://api.tetrascience.com must be listed
$.servers[*].url
warn
tetra-401-response
Authenticated operations should declare a 401 response
$.paths[?(@property.startsWith('/v1'))][get,post,put,delete,patch].responses
info
tetra-429-response
Operations should declare a 429 response for rate-limit handling
$.paths[?(@property.startsWith('/v1'))][get,post,put,delete,patch].responses
warn
tetra-tag-title-case
Tag names should be Title Case (e.g. "Pipelines", not "pipelines")
$.tags[*].name
warn
tetra-path-param-camelcase
Path parameter names should be camelCase
$.paths[*][get,post,put,delete,patch].parameters[?(@.in == 'path')].name
info
tetra-schema-description
Component schemas should include a description
$.components.schemas[*]

Spectral Ruleset

Raw ↑ 
extends:
  - spectral:oas
  - spectral:asyncapi

functionsDir: "./functions"

documentationUrl: https://developers.tetrascience.com/

rules:
  # Operations must declare at least one tag
  operation-tag-defined:
    description: Every operation must declare at least one tag for navigation
    given: $.paths[*][get,post,put,delete,patch]
    severity: error
    then:
      field: tags
      function: truthy

  # Operations must have a summary (Title Case)
  operation-summary-required:
    description: Every operation must have a summary
    given: $.paths[*][get,post,put,delete,patch]
    severity: error
    then:
      field: summary
      function: truthy

  operation-summary-title-case:
    description: Operation summaries should start with a capital letter
    given: $.paths[*][get,post,put,delete,patch].summary
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z]"

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

  # Paths should be lowercase (Tetra uses camelCase resource names e.g. /v1/accessGroups — accept both, but no UPPER_CASE)
  tetra-path-no-uppercase-segments:
    description: Path segments should not be ALL CAPS
    given: $.paths
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: "/[A-Z][A-Z0-9_]+/"

  # All v1 endpoints must declare security
  tetra-secure-v1:
    description: All /v1 operations must require authentication
    given: $.paths[?(@property.startsWith('/v1'))][get,post,put,delete,patch]
    severity: error
    then:
      field: security
      function: truthy

  # Required Tetra auth headers
  tetra-auth-token-defined:
    description: The ts-auth-token apiKey security scheme must be defined
    given: $.components.securitySchemes
    severity: error
    then:
      field: tsAuthToken
      function: truthy

  tetra-org-slug-defined:
    description: The x-org-slug apiKey security scheme must be defined for tenant routing
    given: $.components.securitySchemes
    severity: error
    then:
      field: orgSlug
      function: truthy

  # Production server present
  tetra-production-server:
    description: The production server URL https://api.tetrascience.com must be listed
    given: $.servers[*].url
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^https://api\\.tetrascience(-uat|-dev)?\\.com$"

  # responses must include 401 and 429 for v1 ops
  tetra-401-response:
    description: Authenticated operations should declare a 401 response
    given: $.paths[?(@property.startsWith('/v1'))][get,post,put,delete,patch].responses
    severity: warn
    then:
      field: "401"
      function: truthy

  tetra-429-response:
    description: Operations should declare a 429 response for rate-limit handling
    given: $.paths[?(@property.startsWith('/v1'))][get,post,put,delete,patch].responses
    severity: info
    then:
      field: "429"
      function: truthy

  # Tag names should be Title Case (no lowercase tag names allowed alongside Title Case ones)
  tetra-tag-title-case:
    description: Tag names should be Title Case (e.g. "Pipelines", not "pipelines")
    given: $.tags[*].name
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][A-Za-z0-9 /-]+$"

  # Path parameters should be camelCase, not snake_case
  tetra-path-param-camelcase:
    description: Path parameter names should be camelCase
    given: $.paths[*][get,post,put,delete,patch].parameters[?(@.in == 'path')].name
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  # All schemas in components must have a description
  tetra-schema-description:
    description: Component schemas should include a description
    given: $.components.schemas[*]
    severity: info
    then:
      field: description
      function: truthy