BlueCart · API Governance Rules

BlueCart API Rules

Spectral linting rules defining API design standards and conventions for BlueCart.

44 Rules error 8 warn 22 info 14
View Rules File View on GitHub

Rule Categories

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

Rules

error
info-title-required
API must have a title.
$.info
warn
info-title-bluecart-prefix
API title should reference BlueCart.
$.info.title
warn
info-description-required
API must have a meaningful description.
$.info
error
info-version-required
API must declare a version.
$.info
info
info-contact-required
API should provide contact information.
$.info
warn
openapi-version-3
Specs should be OpenAPI 3.0.x.
$.openapi
error
servers-defined
At least one server must be defined.
$.servers
error
server-https
Servers must use HTTPS.
$.servers[*].url
info
server-description
Servers should be described.
$.servers[*]
error
path-no-query-string
Path keys must not contain a query string.
$.paths[*]~
error
operation-operationId-required
Every operation must have an operationId.
$.paths[*][get,post,put,delete,patch]
warn
operation-operationId-camelcase
operationId should be camelCase.
$.paths[*][get,post,put,delete,patch].operationId
info
operation-operationId-verb-prefix
operationId should begin with a recognised verb.
$.paths[*][get,post,put,delete,patch].operationId
warn
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,delete,patch]
info
operation-summary-title-case
Operation summaries should use Title Case (each word capitalised).
$.paths[*][get,post,put,delete,patch].summary
warn
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,delete,patch]
warn
operation-tags-required
Every operation must have at least one tag.
$.paths[*][get,post,put,delete,patch]
info
operation-microcks-extension
Operations should carry x-microcks-operation for mock compatibility.
$.paths[*][get,post,put,delete,patch]
info
tags-defined
Global tags array should be defined.
$
info
tag-description
Each global tag should have a description.
$.tags[*]
warn
tag-title-case
Tag names should use Title Case.
$.tags[*].name
warn
parameter-description
Parameters should have a description.
$.paths[*][*].parameters[*]
warn
parameter-schema
Parameters should declare a schema with a type.
$.paths[*][*].parameters[*].schema
warn
parameter-camelcase
Query and path parameters should be camelCase (BlueCart convention).
$.paths[*][*].parameters[?(@.in=='query' || @.in=='path')].name
info
parameter-pagination-nexttoken
Cursor pagination parameters should be named nextToken (BlueCart convention).
$.paths[*][*].parameters[?(@.in=='query')].name
warn
request-body-json
Request bodies should use application/json.
$.paths[*][post,put,patch].requestBody.content
warn
response-success-defined
Operations should declare a 2xx success response.
$.paths[*][get,post,put,delete,patch].responses
info
response-unauthorized
Operations should document a 401 response.
$.paths[*][get,post,put,delete,patch].responses
warn
response-description
Every response must have a description.
$.paths[*][*].responses[*]
info
error-schema-message
The Error schema should expose a message field.
$.components.schemas.Error.properties
warn
schema-property-camelcase
Schema property names should be camelCase (BlueCart convention).
$.components.schemas[*].properties[*]~
info
schema-top-level-description
Top-level component schemas should have a description.
$.components.schemas[*]
info
schema-property-type
Schema properties should declare a type (or $ref).
$.components.schemas[*].properties[*]
warn
security-global-defined
A global security requirement should be defined.
$
error
security-schemes-defined
Security schemes must be defined in components.
$.components.securitySchemes
info
security-apikey-header
The API key should be carried in the x-api-key header (BlueCart convention).
$.components.securitySchemes.apiKey
error
get-no-request-body
GET operations must not declare a request body.
$.paths[*].get
warn
delete-no-request-body
DELETE operations should not declare a request body.
$.paths[*].delete
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 camelCase (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 camelCase (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
warn
no-empty-descriptions
Descriptions must not be empty strings.
$..description

Spectral Ruleset

Raw ↑ 
# bluecart — 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)
#   - path-params-casing: snake @ 100% (n=13)
#   - query-params-casing: camel @ 62% (n=21)
#   - operationid-casing: camel @ 100% (n=22)
#   - schema-names-casing: pascal @ 100% (n=20)
#   - schema-properties-casing: camel @ 50% (n=135)
#   - security: global (root) — NOT emitting operation-security-required
#   - error-schema-defined: Error
#   - operation-documents-401: 100% adherence
#   - pagination params observed: ['nextToken']
#   - merge: kept 38 existing, added 6 measured, upgraded 0
#   - added: path-params-casing, query-params-casing, schema-names-casing, schema-properties-casing, error-schema-defined, no-empty-descriptions
extends:
  - spectral:oas
rules:
  info-title-required:
    description: API must have a title.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy
  info-title-bluecart-prefix:
    description: API title should reference BlueCart.
    severity: warn
    given: $.info.title
    then:
      function: pattern
      functionOptions:
        match: BlueCart
  info-description-required:
    description: API must have a meaningful description.
    severity: warn
    given: $.info
    then:
      field: description
      function: truthy
  info-version-required:
    description: API must declare a version.
    severity: error
    given: $.info
    then:
      field: version
      function: truthy
  info-contact-required:
    description: API should provide contact information.
    severity: info
    given: $.info
    then:
      field: contact
      function: truthy
  openapi-version-3:
    description: Specs should be OpenAPI 3.0.x.
    severity: warn
    given: $.openapi
    then:
      function: pattern
      functionOptions:
        match: ^3\.0\.
  servers-defined:
    description: At least one server must be defined.
    severity: error
    given: $.servers
    then:
      function: truthy
  server-https:
    description: Servers must use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^https
  server-description:
    description: Servers should be described.
    severity: info
    given: $.servers[*]
    then:
      field: description
      function: truthy
  path-no-query-string:
    description: Path keys must not contain a query string.
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: \?
  operation-operationId-required:
    description: Every operation must have an operationId.
    severity: error
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: operationId
      function: truthy
  operation-operationId-camelcase:
    description: operationId should be camelCase.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].operationId
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-zA-Z0-9]*$
  operation-operationId-verb-prefix:
    description: operationId should begin with a recognised verb.
    severity: info
    given: $.paths[*][get,post,put,delete,patch].operationId
    then:
      function: pattern
      functionOptions:
        match: ^(get|list|search|retrieve|create|update|delete|place|modify|disable|enable)
  operation-summary-required:
    description: Every operation must have a summary.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: summary
      function: truthy
  operation-summary-title-case:
    description: Operation summaries should use Title Case (each word capitalised).
    severity: info
    given: $.paths[*][get,post,put,delete,patch].summary
    then:
      function: pattern
      functionOptions:
        match: ^([A-Z][A-Za-z0-9/-]*)(\s[A-Za-z0-9/-]+)*$
  operation-description-required:
    description: Every operation must have a description.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: description
      function: truthy
  operation-tags-required:
    description: Every operation must have at least one tag.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: tags
      function: truthy
  operation-microcks-extension:
    description: Operations should carry x-microcks-operation for mock compatibility.
    severity: info
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: x-microcks-operation
      function: truthy
  tags-defined:
    description: Global tags array should be defined.
    severity: info
    given: $
    then:
      field: tags
      function: truthy
  tag-description:
    description: Each global tag should have a description.
    severity: info
    given: $.tags[*]
    then:
      field: description
      function: truthy
  tag-title-case:
    description: Tag names should use Title Case.
    severity: warn
    given: $.tags[*].name
    then:
      function: pattern
      functionOptions:
        match: ^[A-Z][A-Za-z0-9]*( [A-Z][A-Za-z0-9]*)*$
  parameter-description:
    description: Parameters should have a description.
    severity: warn
    given: $.paths[*][*].parameters[*]
    then:
      field: description
      function: truthy
  parameter-schema:
    description: Parameters should declare a schema with a type.
    severity: warn
    given: $.paths[*][*].parameters[*].schema
    then:
      field: type
      function: truthy
  parameter-camelcase:
    description: Query and path parameters should be camelCase (BlueCart convention).
    severity: warn
    given: $.paths[*][*].parameters[?(@.in=='query' || @.in=='path')].name
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-zA-Z0-9]*$
  parameter-pagination-nexttoken:
    description: Cursor pagination parameters should be named nextToken (BlueCart convention).
    severity: info
    given: $.paths[*][*].parameters[?(@.in=='query')].name
    then:
      function: pattern
      functionOptions:
        notMatch: ^(offset|page|cursor|pageToken)$
  request-body-json:
    description: Request bodies should use application/json.
    severity: warn
    given: $.paths[*][post,put,patch].requestBody.content
    then:
      field: application/json
      function: truthy
  response-success-defined:
    description: Operations should declare a 2xx success response.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].responses
    then:
      field: '200'
      function: truthy
  response-unauthorized:
    description: Operations should document a 401 response.
    severity: info
    given: $.paths[*][get,post,put,delete,patch].responses
    then:
      field: '401'
      function: truthy
  response-description:
    description: Every response must have a description.
    severity: warn
    given: $.paths[*][*].responses[*]
    then:
      field: description
      function: truthy
  error-schema-message:
    description: The Error schema should expose a message field.
    severity: info
    given: $.components.schemas.Error.properties
    then:
      field: message
      function: truthy
  schema-property-camelcase:
    description: Schema property names should be camelCase (BlueCart convention).
    severity: warn
    given: $.components.schemas[*].properties[*]~
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-zA-Z0-9]*$
  schema-top-level-description:
    description: Top-level component schemas should have a description.
    severity: info
    given: $.components.schemas[*]
    then:
      field: description
      function: truthy
  schema-property-type:
    description: Schema properties should declare a type (or $ref).
    severity: info
    given: $.components.schemas[*].properties[*]
    then:
      function: defined
  security-global-defined:
    description: A global security requirement should be defined.
    severity: warn
    given: $
    then:
      field: security
      function: truthy
  security-schemes-defined:
    description: Security schemes must be defined in components.
    severity: error
    given: $.components.securitySchemes
    then:
      function: truthy
  security-apikey-header:
    description: The API key should be carried in the x-api-key header (BlueCart convention).
    severity: info
    given: $.components.securitySchemes.apiKey
    then:
      field: name
      function: pattern
      functionOptions:
        match: ^x-api-key$
  get-no-request-body:
    description: GET operations must not declare a request body.
    severity: error
    given: $.paths[*].get
    then:
      field: requestBody
      function: falsy
  delete-no-request-body:
    description: DELETE operations should not declare a request body.
    severity: warn
    given: $.paths[*].delete
    then:
      field: requestBody
      function: falsy
  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 camelCase (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: camel
  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 camelCase (the dominant convention in this API).
    severity: info
    given: $.components.schemas[*].properties
    then:
      field: '@key'
      function: casing
      functionOptions:
        type: camel
  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
  no-empty-descriptions:
    description: Descriptions must not be empty strings.
    severity: warn
    given: $..description
    then:
      function: truthy