TIDAL · API Governance Rules

TIDAL API Rules

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

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

Rule Categories

tidal

Rules

error
tidal-server-base-uri
TIDAL servers must use the openapi.tidal.com/v2 production base.
$.servers[*].url
warn
tidal-jsonapi-content-type
TIDAL is JSON:API; request and response media types should be application/vnd.api+json.
$.paths.*.*.requestBody.content
warn
tidal-jsonapi-response-content-type
JSON:API response media type should be advertised.
$.paths.*.*.responses[?(@property.match(/^2/))].content
warn
tidal-resource-camel-case
TIDAL paths use camelCase resource names (albums, userCollections, trackManifests).
$.paths
warn
tidal-operation-summary
Every operation should have a single-line summary.
$.paths.*.*
info
tidal-cursor-pagination
TIDAL collection endpoints expose JSON:API page[cursor] pagination — list operations should accept a page[cursor] query parameter.
$.paths[?(@property.match(/^\/[a-zA-Z]+$/))].get.parameters[*]
error
tidal-security-required
All TIDAL operations require an OAuth 2.0 bearer token.
$.paths.*.*
info
tidal-include-relationship-naming
JSON:API include query parameters must reference camelCase relationship names.
$.paths.*.get.parameters[?(@.name == "include")]

Spectral Ruleset

Raw ↑ 
extends:
  - "@stoplight/spectral:oas"
rules:
  tidal-server-base-uri:
    description: TIDAL servers must use the openapi.tidal.com/v2 production base.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://openapi\\.tidal\\.com/v2$"
  tidal-jsonapi-content-type:
    description: TIDAL is JSON:API; request and response media types should be application/vnd.api+json.
    severity: warn
    given: $.paths.*.*.requestBody.content
    then:
      function: truthy
      field: "application/vnd.api+json"
  tidal-jsonapi-response-content-type:
    description: JSON:API response media type should be advertised.
    severity: warn
    given: $.paths.*.*.responses[?(@property.match(/^2/))].content
    then:
      function: truthy
      field: "application/vnd.api+json"
  tidal-resource-camel-case:
    description: TIDAL paths use camelCase resource names (albums, userCollections, trackManifests).
    severity: warn
    given: $.paths
    then:
      function: pattern
      field: "@key"
      functionOptions:
        match: "^/[a-z][a-zA-Z]*(/.*)?$"
  tidal-operation-summary:
    description: Every operation should have a single-line summary.
    severity: warn
    given: $.paths.*.*
    then:
      field: summary
      function: truthy
  tidal-cursor-pagination:
    description: TIDAL collection endpoints expose JSON:API page[cursor] pagination — list operations should
      accept a page[cursor] query parameter.
    severity: info
    given: $.paths[?(@property.match(/^\/[a-zA-Z]+$/))].get.parameters[*]
    then:
      function: truthy
  tidal-security-required:
    description: All TIDAL operations require an OAuth 2.0 bearer token.
    severity: error
    given: $.paths.*.*
    then:
      field: security
      function: truthy
  tidal-include-relationship-naming:
    description: JSON:API include query parameters must reference camelCase relationship names.
    severity: info
    given: $.paths.*.get.parameters[?(@.name == "include")]
    then:
      field: schema
      function: truthy