42Crunch · API Governance Rules
42Crunch API Rules
Spectral linting rules defining API design standards and conventions for 42Crunch.
43 Rules
error 12
warn 21
info 10
Rule Categories
delete
examples
get
info
no
openapi
operation
parameter
paths
post
request
response
schema
security
servers
tags
Rules
error
info-title-required
The info object must have a non-empty title.
$.info
warn
info-title-prefix
API title must start with "42Crunch" to identify the provider.
$.info.title
warn
info-description-required
The info object must have a description with at least 30 characters.
$.info
error
info-version-required
The info object must specify a version.
$.info
info
info-contact-required
The info object should include contact information.
$.info
error
openapi-version-3
All specs must use OpenAPI 3.0.x.
$
warn
servers-defined
At least one server must be defined.
$
info
servers-description
Every server must have a description.
$.servers[*]
warn
paths-kebab-case
Path segments must use kebab-case (lowercase letters, numbers, hyphens).
$.paths[*]~
warn
paths-no-trailing-slash
Paths must not end with a trailing slash.
$.paths[*]~
error
paths-no-query-string
Paths must not contain query strings; use parameters instead.
$.paths[*]~
error
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,patch,delete,options,head]
warn
operation-summary-prefix
Operation summaries must start with "42Crunch" for consistency.
$.paths[*][get,post,put,patch,delete,options,head].summary
warn
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,patch,delete,options,head]
error
operation-id-required
Every operation must have an operationId.
$.paths[*][get,post,put,patch,delete,options,head]
warn
operation-id-camel-case
operationId must use camelCase format.
$.paths[*][get,post,put,patch,delete,options,head].operationId
info
operation-id-verb-prefix
operationId should start with a standard verb (list, get, create, update, delete, check, run, search).
$.paths[*][get,post,put,patch,delete,options,head].operationId
error
operation-tags-required
Every operation must have at least one tag.
$.paths[*][get,post,put,patch,delete,options,head]
info
operation-microcks-extension
Operations should include x-microcks-operation for mock server compatibility.
$.paths[*][get,post,put,patch,delete]
warn
tags-global-defined
Global tags array should be defined with descriptions.
$
warn
tags-title-case
Tag names must use Title Case (e.g., "Jobs", "Health", "Logs").
$.tags[*].name
info
tags-description-required
Each global tag should have a description.
$.tags[*]
warn
parameter-description-required
Every parameter must have a description.
$.paths[*][*].parameters[*]
error
parameter-schema-required
Every parameter must have a schema.
$.paths[*][*].parameters[*]
info
parameter-name-kebab-case
Query parameter names should use snake_case or kebab-case.
$.paths[*][*].parameters[?(@.in == 'query')].name
warn
request-body-json-content
Request bodies should specify application/json as content type.
$.paths[*][post,put,patch].requestBody.content
info
request-body-examples
Request body schemas should include examples for documentation and mocking.
$.paths[*][post,put,patch].requestBody.content.application/json
error
response-success-required
Every operation must have at least one 2xx success response.
$.paths[*][get,post,put,patch,delete]
warn
response-400-required
Every operation should have a 400 Bad Request response.
$.paths[*][get,post,put,patch,delete].responses
error
response-description-required
Every response must have a description.
$.paths[*][*].responses[*]
warn
response-json-content
Success responses should return application/json content.
$.paths[*][get,post,put,patch].responses[?(@property.match(/^2/))]
warn
response-error-schema
Error responses (4xx) should use the Error schema with an 'error' field.
$.paths[*][*].responses[?(@property.match(/^4/))]
warn
schema-type-defined
All schemas in components must have a type defined.
$.components.schemas[*]
warn
schema-description-required
All component schemas should have a description.
$.components.schemas[*]
info
schema-properties-description
Schema properties should have descriptions.
$.components.schemas[*].properties[*]
info
schema-additional-properties-false
Schemas should set additionalProperties to false for strict validation.
$.components.schemas[*]
warn
schema-no-empty-properties
Schema properties must not be empty objects without type or $ref.
$.components.schemas[*].properties[*]
warn
security-schemes-described
All security schemes must have descriptions.
$.components.securitySchemes[*]
error
get-no-request-body
GET operations must not have a request body.
$.paths[*].get
warn
delete-no-request-body
DELETE operations should not have a request body.
$.paths[*].delete
warn
post-has-request-body
POST operations should have a request body.
$.paths[*].post
error
no-empty-descriptions
Descriptions must not be empty strings.
$..description
info
examples-encouraged
Schema properties should include example values.
$.components.schemas[*].properties[*]