Tronald Dump · API Governance Rules

Tronald Dump API Rules

Spectral linting rules defining API design standards and conventions for Tronald Dump.

51 Rules error 20 warn 21 info 10
View Rules File View on GitHub

Rule Categories

delete error external get info no openapi operation parameter path paths query response schema security servers tag tags

Rules

error
info-title-prefix
Spec title MUST begin with 'Tronald Dump'.
$.info.title
error
info-description-required
API description MUST be present and at least 60 characters.
$.info.description
warn
info-contact-required
Contact block MUST be present with at least a name.
$.info.contact
warn
info-license-required
License block MUST be defined.
$.info.license
error
info-version-required
Spec version MUST be present.
$.info.version
error
openapi-version-3
Use OpenAPI 3.0.x or 3.1.x.
$.openapi
error
servers-required
At least one server URL MUST be defined.
$.servers
warn
servers-https
Server URLs MUST use https.
$.servers[*].url
warn
servers-description-required
Each server entry MUST include a description.
$.servers[*]
warn
paths-kebab-case-or-template
Path segments MUST be lowercase kebab-case or {snake_case} templates.
$.paths.*~
error
paths-no-trailing-slash
Paths MUST NOT end with a trailing slash.
$.paths.*~
error
paths-no-query-string
Paths MUST NOT contain a query string.
$.paths.*~
warn
paths-no-file-extensions
Paths SHOULD NOT carry file extensions (.json, .xml).
$.paths.*~
error
operation-operationid-required
Every operation MUST have an operationId.
$.paths.*[get,post,put,patch,delete]
error
operation-operationid-camel-case
operationId MUST be camelCase.
$.paths.*[get,post,put,patch,delete].operationId
warn
operation-operationid-verb-prefix
operationId SHOULD start with a verb (get, list, search, create, update, delete).
$.paths.*[get,post,put,patch,delete].operationId
error
operation-summary-required
Every operation MUST have a summary.
$.paths.*[get,post,put,patch,delete]
warn
operation-summary-prefix
Operation summaries SHOULD begin with 'Tronald Dump'.
$.paths.*[get,post,put,patch,delete].summary
error
operation-description-required
Every operation MUST have a description.
$.paths.*[get,post,put,patch,delete]
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 include x-microcks-operation for mock compatibility.
$.paths.*[get,post,put,patch,delete]
warn
tags-global-defined
Top-level tags array MUST be defined.
$.tags
warn
tag-description-required
Every global tag MUST have a description.
$.tags[*]
warn
tag-title-case
Tag names MUST be Title Case (single capitalized word or capitalized words separated by spaces).
$.tags[*].name
error
parameter-description-required
Every parameter MUST have a description.
$.paths.*.*.parameters[*]
warn
parameter-snake-case
Parameter names MUST be snake_case.
$.paths.*.*.parameters[*].name
error
parameter-schema-required
Every parameter MUST have a schema with a type.
$.paths.*.*.parameters[*]
warn
parameter-pagination-standard
Pagination parameters MUST be named 'page' and 'size' (Tronald Dump convention).
$.paths.*.*.parameters[?(@.in=='query' && (@.name=='offset' || @.name=='limit' || @.name=='per_page' || @.name=='pageSize'))]
info
parameter-example-encouraged
Parameters SHOULD include an example value.
$.paths.*.*.parameters[*]
error
response-200-required
Every GET operation MUST define a 200 response.
$.paths.*.get.responses
warn
response-404-on-id-paths
Path operations with an ID parameter SHOULD define a 404 response.
$.paths[?(@property.match(/\{.+\}/))].*.responses
info
response-500-encouraged
Operations SHOULD document a 500 response.
$.paths.*[get,post,put,patch,delete].responses
error
response-description-required
Every response MUST have a description.
$.paths.*.*.responses.*
info
response-hal-content-type
Successful responses SHOULD use application/hal+json (HAL convention).
$.paths.*.*.responses[?(@property.match(/^2\d{2}$/))].content
info
response-example-encouraged
Responses SHOULD include at least one named example.
$.paths.*.*.responses.*.content.*
warn
schema-snake-case-properties
Schema property names MUST be snake_case (except HAL conventions _links, _embedded).
$.components.schemas.*.properties.*~
warn
schema-description-required
Top-level component schemas MUST have a description.
$.components.schemas.*
error
schema-type-required
Schemas MUST declare a type.
$.components.schemas.*
info
schema-id-suffix
Unique identifier properties SHOULD be named with an _id suffix.
$.components.schemas.*.properties[?(@property == 'id' || @property == 'identifier')]~
info
schema-hal-links-on-resources
Resource schemas SHOULD include a _links property for HAL hypermedia.
$.components.schemas[?(@property.match(/^(Quote|Author|Source|Tag)$/))].properties
info
security-not-required-public-api
Tronald Dump is a public, no-auth API. The global `security` field SHOULD be omitted.
$.security
error
get-no-request-body
GET operations MUST NOT define a request body.
$.paths.*.get
error
delete-no-request-body
DELETE operations MUST NOT define a request body.
$.paths.*.delete
error
no-empty-description
Descriptions MUST NOT be empty strings.
$..description
info
external-docs-encouraged
Spec SHOULD include externalDocs pointing at provider documentation.
$.externalDocs
warn
servers-expected-domain
Server URLs should be on the tronalddump.io domain.
$.servers[*].url
warn
path-params-casing
Path parameters should be snake_case (the dominant convention in this API).
$.paths[*].parameters[?(@.in=='path')].name
warn
query-params-casing
Query parameters should be snake_case (the dominant convention in this API).
$.paths[*][get,post,put,patch,delete].parameters[?(@.in=='query')]
warn
schema-names-casing
Component schema names should be PascalCase (the dominant convention in this API).
$.components.schemas
info
schema-properties-casing
Schema properties should be snake_case (the dominant convention in this API).
$.components.schemas[*].properties
warn
error-schema-defined
A shared error schema (Error) should be defined for error payloads.
$.components.schemas

Spectral Ruleset

Raw ↑ 
# tronald-dump — Spectral ruleset (strengthened)
# Plain Spectral. Existing hand-authored rules preserved; measured rules added
# from this provider's own OpenAPI conventions by strengthen_ruleset.py,
# then self-validated against the spec.
#
# Provenance:
#   - servers-https-only: 100% of servers already https (error)
#   - servers-expected-domain: 1/1 servers on tronalddump.io
#   - path-params-casing: snake @ 100% (n=4)
#   - query-params-casing: snake @ 100% (n=5)
#   - operationid-casing: camel @ 100% (n=9)
#   - schema-names-casing: pascal @ 100% (n=9)
#   - schema-properties-casing: snake @ 67% (n=39)
#   - error-schema-defined: Error
#   - operation-documents-500: 100% adherence
#   - pagination params observed: ['page', 'size']
#   - merge: kept 45 existing, added 6 measured, upgraded 0
#   - added: servers-expected-domain, path-params-casing, query-params-casing, schema-names-casing, schema-properties-casing, error-schema-defined
extends:
  - spectral:oas
rules:
  info-title-prefix:
    description: Spec title MUST begin with 'Tronald Dump'.
    severity: error
    given: $.info.title
    then:
      function: pattern
      functionOptions:
        match: ^Tronald Dump
  info-description-required:
    description: API description MUST be present and at least 60 characters.
    severity: error
    given: $.info.description
    then:
      function: length
      functionOptions:
        min: 60
  info-contact-required:
    description: Contact block MUST be present with at least a name.
    severity: warn
    given: $.info.contact
    then:
      field: name
      function: truthy
  info-license-required:
    description: License block MUST be defined.
    severity: warn
    given: $.info.license
    then:
      function: truthy
  info-version-required:
    description: Spec version MUST be present.
    severity: error
    given: $.info.version
    then:
      function: truthy
  openapi-version-3:
    description: Use OpenAPI 3.0.x or 3.1.x.
    severity: error
    given: $.openapi
    then:
      function: pattern
      functionOptions:
        match: ^3\.
  servers-required:
    description: At least one server URL MUST be defined.
    severity: error
    given: $.servers
    then:
      function: length
      functionOptions:
        min: 1
  servers-https:
    description: Server URLs MUST use https.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^https://
  servers-description-required:
    description: Each server entry MUST include a description.
    severity: warn
    given: $.servers[*]
    then:
      field: description
      function: truthy
  paths-kebab-case-or-template:
    description: Path segments MUST be lowercase kebab-case or {snake_case} templates.
    severity: warn
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        match: ^(/[a-z0-9-]+|/\{[a-z0-9_]+\})+$
  paths-no-trailing-slash:
    description: Paths MUST NOT end with a trailing slash.
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: .+/$
  paths-no-query-string:
    description: Paths MUST NOT contain a query string.
    severity: error
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: \?
  paths-no-file-extensions:
    description: Paths SHOULD NOT carry file extensions (.json, .xml).
    severity: warn
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        notMatch: \.(json|xml|html)$
  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.
    severity: error
    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 verb (get, list, search, create, update, delete).
    severity: warn
    given: $.paths.*[get,post,put,patch,delete].operationId
    then:
      function: pattern
      functionOptions:
        match: ^(get|list|search|create|update|delete|find|lookup)
  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-summary-prefix:
    description: Operation summaries SHOULD begin with 'Tronald Dump'.
    severity: warn
    given: $.paths.*[get,post,put,patch,delete].summary
    then:
      function: pattern
      functionOptions:
        match: ^Tronald Dump
  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-tags-required:
    description: Every operation MUST have at least one tag.
    severity: error
    given: $.paths.*[get,post,put,patch,delete]
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1
  operation-microcks-extension:
    description: Every operation SHOULD include x-microcks-operation for mock compatibility.
    severity: info
    given: $.paths.*[get,post,put,patch,delete]
    then:
      field: x-microcks-operation
      function: truthy
  tags-global-defined:
    description: Top-level tags array MUST be defined.
    severity: warn
    given: $.tags
    then:
      function: length
      functionOptions:
        min: 1
  tag-description-required:
    description: Every global tag MUST have a description.
    severity: warn
    given: $.tags[*]
    then:
      field: description
      function: truthy
  tag-title-case:
    description: Tag names MUST be Title Case (single capitalized word or capitalized words separated
      by spaces).
    severity: warn
    given: $.tags[*].name
    then:
      function: pattern
      functionOptions:
        match: ^[A-Z][a-zA-Z0-9]*( [A-Z][a-zA-Z0-9]*)*$
  parameter-description-required:
    description: Every parameter MUST have a description.
    severity: error
    given: $.paths.*.*.parameters[*]
    then:
      field: description
      function: truthy
  parameter-snake-case:
    description: Parameter names MUST be snake_case.
    severity: warn
    given: $.paths.*.*.parameters[*].name
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-z0-9_]*$
  parameter-schema-required:
    description: Every parameter MUST have a schema with a type.
    severity: error
    given: $.paths.*.*.parameters[*]
    then:
      field: schema
      function: truthy
  parameter-pagination-standard:
    description: Pagination parameters MUST be named 'page' and 'size' (Tronald Dump convention).
    severity: warn
    given: $.paths.*.*.parameters[?(@.in=='query' && (@.name=='offset' || @.name=='limit' || @.name=='per_page'
      || @.name=='pageSize'))]
    then:
      function: falsy
  parameter-example-encouraged:
    description: Parameters SHOULD include an example value.
    severity: info
    given: $.paths.*.*.parameters[*]
    then:
      field: example
      function: truthy
  response-200-required:
    description: Every GET operation MUST define a 200 response.
    severity: error
    given: $.paths.*.get.responses
    then:
      field: '200'
      function: truthy
  response-404-on-id-paths:
    description: Path operations with an ID parameter SHOULD define a 404 response.
    severity: warn
    given: $.paths[?(@property.match(/\{.+\}/))].*.responses
    then:
      field: '404'
      function: truthy
  response-500-encouraged:
    description: Operations SHOULD document a 500 response.
    severity: info
    given: $.paths.*[get,post,put,patch,delete].responses
    then:
      field: '500'
      function: truthy
  response-description-required:
    description: Every response MUST have a description.
    severity: error
    given: $.paths.*.*.responses.*
    then:
      field: description
      function: truthy
  response-hal-content-type:
    description: Successful responses SHOULD use application/hal+json (HAL convention).
    severity: info
    given: $.paths.*.*.responses[?(@property.match(/^2\d{2}$/))].content
    then:
      field: application/hal+json
      function: truthy
  response-example-encouraged:
    description: Responses SHOULD include at least one named example.
    severity: info
    given: $.paths.*.*.responses.*.content.*
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
          - required:
            - example
          - required:
            - examples
  schema-snake-case-properties:
    description: Schema property names MUST be snake_case (except HAL conventions _links, _embedded).
    severity: warn
    given: $.components.schemas.*.properties.*~
    then:
      function: pattern
      functionOptions:
        match: ^(_links|_embedded|[a-z][a-z0-9_]*)$
  schema-description-required:
    description: Top-level component schemas MUST have a description.
    severity: warn
    given: $.components.schemas.*
    then:
      field: description
      function: truthy
  schema-type-required:
    description: Schemas MUST declare a type.
    severity: error
    given: $.components.schemas.*
    then:
      field: type
      function: truthy
  schema-id-suffix:
    description: Unique identifier properties SHOULD be named with an _id suffix.
    severity: info
    given: $.components.schemas.*.properties[?(@property == 'id' || @property == 'identifier')]~
    then:
      function: falsy
  schema-hal-links-on-resources:
    description: Resource schemas SHOULD include a _links property for HAL hypermedia.
    severity: info
    given: $.components.schemas[?(@property.match(/^(Quote|Author|Source|Tag)$/))].properties
    then:
      field: _links
      function: truthy
  security-not-required-public-api:
    description: Tronald Dump is a public, no-auth API. The global `security` field SHOULD be omitted.
    severity: info
    given: $.security
    then:
      function: falsy
  get-no-request-body:
    description: GET operations MUST NOT define a request body.
    severity: error
    given: $.paths.*.get
    then:
      field: requestBody
      function: falsy
  delete-no-request-body:
    description: DELETE operations MUST NOT define a request body.
    severity: error
    given: $.paths.*.delete
    then:
      field: requestBody
      function: falsy
  no-empty-description:
    description: Descriptions MUST NOT be empty strings.
    severity: error
    given: $..description
    then:
      function: truthy
  external-docs-encouraged:
    description: Spec SHOULD include externalDocs pointing at provider documentation.
    severity: info
    given: $.externalDocs
    then:
      function: truthy
  servers-expected-domain:
    description: Server URLs should be on the tronalddump.io domain.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: tronalddump\.io
  path-params-casing:
    description: Path parameters should be snake_case (the dominant convention in this API).
    severity: warn
    given: $.paths[*].parameters[?(@.in=='path')].name
    then:
      function: casing
      functionOptions:
        type: snake
  query-params-casing:
    description: Query parameters should be snake_case (the dominant convention in this API).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.in=='query')]
    then:
      field: name
      function: casing
      functionOptions:
        type: snake
  schema-names-casing:
    description: Component schema names should be PascalCase (the dominant convention in this API).
    severity: warn
    given: $.components.schemas
    then:
      field: '@key'
      function: casing
      functionOptions:
        type: pascal
  schema-properties-casing:
    description: Schema properties should be snake_case (the dominant convention in this API).
    severity: info
    given: $.components.schemas[*].properties
    then:
      field: '@key'
      function: casing
      functionOptions:
        type: snake
  error-schema-defined:
    description: A shared error schema (Error) should be defined for error payloads.
    severity: warn
    given: $.components.schemas
    then:
      field: Error
      function: truthy