Block · API Governance Rules
Block API Rules
Spectral linting rules defining API design standards and conventions for Block.
29 Rules
error 11
warn 15
info 3
Rule Categories
block
Rules
error
block-info-title
API must have a title
$.info
error
block-info-description
API must have a description
$.info
error
block-info-version
API must have a version
$.info
warn
block-info-contact
API must have contact information
$.info
error
block-servers-exist
API must have at least one server defined
$
error
block-server-https
Production server must use HTTPS
$.servers[*]
warn
block-server-description
Each server must have a description
$.servers[*]
warn
block-path-kebab-case
Path segments must use kebab-case or snake_case
$.paths[*]~
error
block-path-no-trailing-slash
Paths must not have trailing slashes
$.paths[*]~
error
block-operation-id-exists
Every operation must have an operationId
$.paths[*][get,post,put,patch,delete,head,options,trace]
warn
block-operation-id-kebab-case
OperationId must use kebab-case
$.paths[*][get,post,put,patch,delete,head,options,trace]
error
block-operation-summary-exists
Every operation must have a summary
$.paths[*][get,post,put,patch,delete,head,options,trace]
warn
block-operation-summary-title-case
Operation summary must use title case and start with Block Square
$.paths[*][get,post,put,patch,delete,head,options,trace]
warn
block-operation-description-exists
Every operation must have a description
$.paths[*][get,post,put,patch,delete,head,options,trace]
warn
block-operation-tags
Every operation must have at least one tag
$.paths[*][get,post,put,patch,delete,head,options,trace]
warn
block-parameter-description
All parameters must have a description
$.paths[*][*].parameters[*]
error
block-parameter-schema
All parameters must have a schema
$.paths[*][*].parameters[*]
warn
block-request-body-description
Request bodies should have a description
$.paths[*][*].requestBody
error
block-response-success-exists
Operations must have at least one 2xx response
$.paths[*][get,post,put,patch,delete]
warn
block-response-schema-exists
Success responses must have a content schema
$.paths[*][*].responses[200,201].content[*]
warn
block-response-examples
Responses should include examples
$.paths[*][*].responses[200,201].content[*]
error
block-security-scheme-defined
API must define security schemes
$.components
warn
block-global-security
API should have global security defined
$
warn
block-schema-type
All schema objects must have a type
$.components.schemas[*]
warn
block-schema-description
All schema components must have a description
$.components.schemas[*]
info
block-property-description
Schema properties should have descriptions
$.components.schemas[*].properties[*]
warn
block-idempotency-key
POST operations creating resources should require idempotency_key
$.paths[*].post.requestBody.content[*].schema.required[*]
info
block-money-object
Money amounts should use the Money object pattern with amount and currency
$.components.schemas[*].properties[*_money]
info
block-cursor-pagination
List operations should support cursor-based pagination
$.paths[*].get.parameters[*]