Fortnite Tracker · API Governance Rules

Fortnite Tracker API Rules

Spectral linting rules defining API design standards and conventions for Fortnite Tracker.

44 Rules error 20 warn 21 info 3
View Rules File View on GitHub

Rule Categories

external info method no openapi operation parameter paths response schema security servers tags

Rules

warn
info-title-fortnite-tracker-prefix
info.title must start with 'Fortnite Tracker'.
$.info.title
error
info-description-required
info.description is required and must be at least 80 characters.
$.info
error
info-version-required
info.version is required.
$.info
warn
info-contact-required
info.contact should be present so consumers know where to reach support.
$.info
warn
info-license-required
info.license should be present (Tracker Network Terms of Service).
$.info
error
openapi-version-3
Spec must be OpenAPI 3.x.
$.openapi
error
servers-defined
servers must be defined.
$
error
servers-https-only
All server URLs must use HTTPS.
$.servers[*].url
warn
servers-fortnite-tracker-host
Primary server should be api.fortnitetracker.com.
$.servers[*].url
warn
servers-v1-prefix
Server URL must end in /v1 — Fortnite Tracker only ships a v1 surface.
$.servers[*].url
warn
paths-kebab-case
Path segments must be lowercase kebab-case (alphanumerics, hyphens, path params).
$.paths[*]~
error
paths-no-trailing-slash
Paths must not have trailing slashes.
$.paths[*]~
error
paths-no-query-string
Paths must not include query strings.
$.paths[*]~
error
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,patch,delete]
error
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,patch,delete]
warn
operation-summary-fortnite-tracker-prefix
Operation summary should start with 'Fortnite Tracker '.
$.paths[*][get,post,put,patch,delete].summary
error
operation-operationid-required
Every operation must have an operationId.
$.paths[*][get,post,put,patch,delete]
warn
operation-operationid-camel-case
operationId must be camelCase (verb-noun).
$.paths[*][get,post,put,patch,delete].operationId
warn
operation-operationid-verb-prefix
operationId should start with a known verb (get, list, create, update, delete).
$.paths[*][get,post,put,patch,delete].operationId
error
operation-tags-required
Every operation must have at least one tag.
$.paths[*][get,post,put,patch,delete]
info
operation-microcks-extension
Every operation should have an x-microcks-operation extension for mock-server compatibility.
$.paths[*][get,post,put,patch,delete]
warn
tags-global-defined
Global tags array must be defined.
$
warn
tags-description-required
Every global tag must have a description.
$.tags[*]
warn
tags-title-case
Tag names should be in Title Case (e.g., 'Power Rankings', 'Store').
$.tags[*].name
error
parameter-description-required
Every parameter must have a description.
$.paths[*][get,post,put,patch,delete].parameters[*]
error
parameter-schema-required
Every parameter must have a schema.
$.paths[*][get,post,put,patch,delete].parameters[*]
warn
parameter-camel-case
Parameter names must be camelCase.
$.paths[*][get,post,put,patch,delete].parameters[*].name
info
parameter-example-encouraged
Parameters should include an example value.
$.paths[*][get,post,put,patch,delete].parameters[*]
error
response-200-required
GET endpoints must define a 200 response.
$.paths[*].get.responses
warn
response-401-required
All operations must define a 401 response (TRN-Api-Key required).
$.paths[*][get,post,put,patch,delete].responses
warn
response-429-required
All operations should define a 429 response (rate limiting).
$.paths[*][get,post,put,patch,delete].responses
error
response-description-required
Every response must have a description.
$.paths[*][get,post,put,patch,delete].responses[*]
warn
response-json-content-type
Responses should serve application/json.
$.paths[*][get,post,put,patch,delete].responses[*].content
warn
response-error-schema-fields
Error response schemas must include error and message fields.
$.components.schemas.Error.properties
warn
schema-property-camel-case
Schema property names must be camelCase to match Tracker Network's wire format.
$.components.schemas[*].properties[*]~
warn
schema-top-level-description
Top-level schemas must have a description.
$.components.schemas[*]
warn
schema-type-required
Top-level schemas must declare a type.
$.components.schemas[*]
error
security-global-defined
Global security must be defined (TRN-Api-Key required on every call).
$
error
security-scheme-defined
components.securitySchemes must declare the trnApiKey scheme.
$.components.securitySchemes
error
security-trn-api-key-header
TRN-Api-Key must be defined as an apiKey security scheme in the header.
$.components.securitySchemes.trnApiKey
error
method-get-no-request-body
GET operations must not declare a requestBody.
$.paths[*].get
error
method-delete-no-request-body
DELETE operations must not declare a requestBody.
$.paths[*].delete
warn
no-empty-description
Description fields must not be empty strings.
$..description
info
external-docs-encouraged
Spec should reference external docs (fortnitetracker.com/site-api).
$

Spectral Ruleset

Raw ↑ 
# Fortnite Tracker Spectral Ruleset
#
# Enforces the conventions observed in the Fortnite Tracker API
# (api.fortnitetracker.com/v1) profile. Single-version, /v1-prefixed REST
# surface with kebab-case paths, camelCase operationIds, lowercase enum tokens,
# TRN-Api-Key header auth, and tight tag groupings (Profile, Leaderboards,
# Power Rankings, Store, Challenges).
#
# Rule names are kebab-cased and grouped by category prefix:
#   info-*, paths-*, operation-*, parameter-*, response-*, schema-*, security-*, tag-*
#
extends: "spectral:oas"

rules:

  # ────────────────────────────────────────────────────────────────
  # INFO / METADATA
  # ────────────────────────────────────────────────────────────────

  info-title-fortnite-tracker-prefix:
    description: "info.title must start with 'Fortnite Tracker'."
    message: "{{property}} should start with 'Fortnite Tracker'."
    severity: warn
    given: "$.info.title"
    then:
      function: pattern
      functionOptions:
        match: "^Fortnite Tracker"

  info-description-required:
    description: "info.description is required and must be at least 80 characters."
    severity: error
    given: "$.info"
    then:
      field: description
      function: length
      functionOptions:
        min: 80

  info-version-required:
    description: "info.version is required."
    severity: error
    given: "$.info"
    then:
      field: version
      function: truthy

  info-contact-required:
    description: "info.contact should be present so consumers know where to reach support."
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy

  info-license-required:
    description: "info.license should be present (Tracker Network Terms of Service)."
    severity: warn
    given: "$.info"
    then:
      field: license
      function: truthy

  # ────────────────────────────────────────────────────────────────
  # OPENAPI VERSION
  # ────────────────────────────────────────────────────────────────

  openapi-version-3:
    description: "Spec must be OpenAPI 3.x."
    severity: error
    given: "$.openapi"
    then:
      function: pattern
      functionOptions:
        match: "^3\\."

  # ────────────────────────────────────────────────────────────────
  # SERVERS
  # ────────────────────────────────────────────────────────────────

  servers-defined:
    description: "servers must be defined."
    severity: error
    given: "$"
    then:
      field: servers
      function: truthy

  servers-https-only:
    description: "All server URLs must use HTTPS."
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  servers-fortnite-tracker-host:
    description: "Primary server should be api.fortnitetracker.com."
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "api\\.fortnitetracker\\.com"

  servers-v1-prefix:
    description: "Server URL must end in /v1 — Fortnite Tracker only ships a v1 surface."
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "/v1$"

  # ────────────────────────────────────────────────────────────────
  # PATHS — NAMING CONVENTIONS
  # ────────────────────────────────────────────────────────────────

  paths-kebab-case:
    description: "Path segments must be lowercase kebab-case (alphanumerics, hyphens, path params)."
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9-]+|/\\{[a-zA-Z0-9]+\\})+$"

  paths-no-trailing-slash:
    description: "Paths must not have trailing slashes."
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        notMatch: "/$"

  paths-no-query-string:
    description: "Paths must not include query strings."
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        notMatch: "\\?"

  # ────────────────────────────────────────────────────────────────
  # OPERATIONS
  # ────────────────────────────────────────────────────────────────

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

  operation-description-required:
    description: "Every operation must have a description."
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  operation-summary-fortnite-tracker-prefix:
    description: "Operation summary should start with 'Fortnite Tracker '."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^Fortnite Tracker "

  operation-operationid-required:
    description: "Every operation must have an operationId."
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  operation-operationid-camel-case:
    description: "operationId must be camelCase (verb-noun)."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  operation-operationid-verb-prefix:
    description: "operationId should start with a known verb (get, list, create, update, delete)."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^(get|list|create|update|delete)"

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

  operation-microcks-extension:
    description: "Every operation should have an x-microcks-operation extension for mock-server compatibility."
    severity: info
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: x-microcks-operation
      function: truthy

  # ────────────────────────────────────────────────────────────────
  # TAGS
  # ────────────────────────────────────────────────────────────────

  tags-global-defined:
    description: "Global tags array must be defined."
    severity: warn
    given: "$"
    then:
      field: tags
      function: truthy

  tags-description-required:
    description: "Every global tag must have a description."
    severity: warn
    given: "$.tags[*]"
    then:
      field: description
      function: truthy

  tags-title-case:
    description: "Tag names should be in Title Case (e.g., 'Power Rankings', 'Store')."
    severity: warn
    given: "$.tags[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]+( [A-Z][a-zA-Z0-9]+)*$"

  # ────────────────────────────────────────────────────────────────
  # PARAMETERS
  # ────────────────────────────────────────────────────────────────

  parameter-description-required:
    description: "Every parameter must have a description."
    severity: error
    given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
    then:
      field: description
      function: truthy

  parameter-schema-required:
    description: "Every parameter must have a schema."
    severity: error
    given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
    then:
      field: schema
      function: truthy

  parameter-camel-case:
    description: "Parameter names must be camelCase."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].parameters[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  parameter-example-encouraged:
    description: "Parameters should include an example value."
    severity: info
    given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
    then:
      field: example
      function: truthy

  # ────────────────────────────────────────────────────────────────
  # RESPONSES
  # ────────────────────────────────────────────────────────────────

  response-200-required:
    description: "GET endpoints must define a 200 response."
    severity: error
    given: "$.paths[*].get.responses"
    then:
      field: '200'
      function: truthy

  response-401-required:
    description: "All operations must define a 401 response (TRN-Api-Key required)."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: '401'
      function: truthy

  response-429-required:
    description: "All operations should define a 429 response (rate limiting)."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: '429'
      function: truthy

  response-description-required:
    description: "Every response must have a description."
    severity: error
    given: "$.paths[*][get,post,put,patch,delete].responses[*]"
    then:
      field: description
      function: truthy

  response-json-content-type:
    description: "Responses should serve application/json."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses[*].content"
    then:
      field: application/json
      function: truthy

  response-error-schema-fields:
    description: "Error response schemas must include error and message fields."
    severity: warn
    given: "$.components.schemas.Error.properties"
    then:
      field: message
      function: truthy

  # ────────────────────────────────────────────────────────────────
  # SCHEMAS — PROPERTY NAMING
  # ────────────────────────────────────────────────────────────────

  schema-property-camel-case:
    description: "Schema property names must be camelCase to match Tracker Network's wire format."
    severity: warn
    given: "$.components.schemas[*].properties[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  schema-top-level-description:
    description: "Top-level schemas must have a description."
    severity: warn
    given: "$.components.schemas[*]"
    then:
      field: description
      function: truthy

  schema-type-required:
    description: "Top-level schemas must declare a type."
    severity: warn
    given: "$.components.schemas[*]"
    then:
      field: type
      function: truthy

  # ────────────────────────────────────────────────────────────────
  # SECURITY
  # ────────────────────────────────────────────────────────────────

  security-global-defined:
    description: "Global security must be defined (TRN-Api-Key required on every call)."
    severity: error
    given: "$"
    then:
      field: security
      function: truthy

  security-scheme-defined:
    description: "components.securitySchemes must declare the trnApiKey scheme."
    severity: error
    given: "$.components.securitySchemes"
    then:
      field: trnApiKey
      function: truthy

  security-trn-api-key-header:
    description: "TRN-Api-Key must be defined as an apiKey security scheme in the header."
    severity: error
    given: "$.components.securitySchemes.trnApiKey"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - type
            - in
            - name
          properties:
            type:
              const: apiKey
            in:
              const: header
            name:
              const: TRN-Api-Key

  # ────────────────────────────────────────────────────────────────
  # HTTP METHOD CONVENTIONS
  # ────────────────────────────────────────────────────────────────

  method-get-no-request-body:
    description: "GET operations must not declare a requestBody."
    severity: error
    given: "$.paths[*].get"
    then:
      field: requestBody
      function: falsy

  method-delete-no-request-body:
    description: "DELETE operations must not declare a requestBody."
    severity: error
    given: "$.paths[*].delete"
    then:
      field: requestBody
      function: falsy

  # ────────────────────────────────────────────────────────────────
  # GENERAL QUALITY
  # ────────────────────────────────────────────────────────────────

  no-empty-description:
    description: "Description fields must not be empty strings."
    severity: warn
    given: "$..description"
    then:
      function: length
      functionOptions:
        min: 1

  external-docs-encouraged:
    description: "Spec should reference external docs (fortnitetracker.com/site-api)."
    severity: info
    given: "$"
    then:
      field: externalDocs
      function: truthy