Charles University · API Governance Rules

Charles University API Rules

Spectral linting rules defining API design standards and conventions for Charles University.

6 Rules error 2 warn 3 info 1
View Rules File View on GitHub

Rule Categories

charles

Rules

error
charles-info-title-required
API must declare an info title.
$.info
error
charles-server-https
Servers must use HTTPS as observed on LINDAT.
$.servers[*].url
warn
charles-operation-id-required
Every operation must have an operationId (LINDAT uses snake_case ids like get_model_collection).
$.paths[*][get,post,put,delete,patch]
warn
charles-operation-id-snake-case
operationIds follow snake_case convention.
$.paths[*][get,post,put,delete,patch].operationId
warn
charles-operation-tagged
Operations are grouped under root, languages, or models tags.
$.paths[*][get,post,put,delete,patch]
info
charles-hal-links-property
Resource schemas expose HAL-style _links navigation.
$.components.schemas[?(@property.match(/Resource$/))].properties

Spectral Ruleset

Raw ↑ 
extends: []
formats:
  - oas3
documentationUrl: https://lindat.mff.cuni.cz/services/translation/docs
rules:
  charles-info-title-required:
    description: API must declare an info title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy
  charles-server-https:
    description: Servers must use HTTPS as observed on LINDAT.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"
  charles-operation-id-required:
    description: Every operation must have an operationId (LINDAT uses snake_case ids like get_model_collection).
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: operationId
      function: truthy
  charles-operation-id-snake-case:
    description: operationIds follow snake_case convention.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].operationId
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"
  charles-operation-tagged:
    description: Operations are grouped under root, languages, or models tags.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: tags
      function: truthy
  charles-hal-links-property:
    description: Resource schemas expose HAL-style _links navigation.
    severity: info
    given: $.components.schemas[?(@property.match(/Resource$/))].properties
    then:
      field: _links
      function: truthy