Paytronix · API Governance Rules

Paytronix API Rules

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

39 Rules error 5 warn 21 info 13
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

warn
info-title-paytronix-prefix
API title should begin with "Paytronix".
$.info.title
warn
info-description-required
Info object must have a non-trivial description.
$.info
error
info-version-required
Info object must declare a version.
$.info
info
info-contact-required
Info object should declare a contact.
$.info
warn
openapi-version-3
Specs should target OpenAPI 3.0.x.
$.openapi
error
servers-defined
At least one server must be defined.
$
warn
server-https
Server URLs must use HTTPS.
$.servers[*].url
info
server-description
Each server should have a description.
$.servers[*]
warn
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,delete,patch]
warn
operation-summary-title-case
Operation summaries must use Title Case (each word capitalized).
$.paths[*][get,post,put,delete,patch].summary
warn
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,delete,patch]
error
operation-operationid-required
Every operation must have an operationId.
$.paths[*][get,post,put,delete,patch]
warn
operation-operationid-camelcase
operationId must be camelCase.
$.paths[*][get,post,put,delete,patch].operationId
info
operation-operationid-verb-prefix
operationId should start with a known verb prefix.
$.paths[*][get,post,put,delete,patch].operationId
warn
operation-tags-required
Every operation must declare at least one tag.
$.paths[*][get,post,put,delete,patch]
info
operation-microcks-extension
Each operation should carry an x-microcks-operation extension for mock compatibility.
$.paths[*][get,post,put,delete,patch]
warn
tags-global-defined
A global tags array must be defined.
$
info
tag-description
Each global tag should have a description.
$.tags[*]
warn
tag-title-case
Tag names must use Title Case.
$.tags[*].name
warn
parameter-description-required
Every parameter must have a description.
$.paths[*][get,post,put,delete,patch].parameters[*]
warn
parameter-schema-typed
Every parameter schema must declare a type.
$.paths[*][get,post,put,delete,patch].parameters[*].schema
info
parameter-camelcase
Query and path parameter names should be camelCase (PXS) or snake_case (Open Dining search).
$.paths[*][get,post,put,delete,patch].parameters[*].name
warn
request-body-json
Request bodies should provide an application/json media type.
$.paths[*][post,put,patch].requestBody.content
warn
request-body-schema
Request body JSON media type must reference a schema.
$.paths[*][post,put,patch].requestBody.content.application/json
error
response-2xx-required
Every operation must define a 2xx success response.
$.paths[*][get,post,put,delete,patch].responses
warn
response-description-required
Every response must have a description.
$.paths[*][get,post,put,delete,patch].responses[*]
info
response-json-content
2xx responses should provide application/json content.
$.paths[*][get,post,put,delete,patch].responses[200,201].content
info
schema-property-typed
Schema properties should declare a type, $ref, or composition.
$.components.schemas[*].properties[*]
info
schema-property-camelcase
Schema property names should be camelCase (PXS convention).
$.components.schemas[*].properties.*~
info
security-schemes-defined
components.securitySchemes should be defined where the API requires auth.
$.components
info
security-scheme-described
Each security scheme should have a description.
$.components.securitySchemes[*]
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 camelCase (the dominant convention in this API).
$.paths[*].parameters[?(@.in=='path')].name
info
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 (ErrorReply) should be defined for error payloads.
$.components.schemas
warn
no-empty-descriptions
Descriptions must not be empty strings.
$..description

Spectral Ruleset

Raw ↑ 
# paytronix — 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: camel @ 100% (n=4)
#   - query-params-casing: camel @ 51% (n=43)
#   - operationid-casing: camel @ 100% (n=30)
#   - schema-names-casing: pascal @ 100% (n=47)
#   - schema-properties-casing: camel @ 52% (n=223)
#   - security: global (root) — NOT emitting operation-security-required
#   - error-schema-defined: ErrorReply
#   - pagination params observed: ['limit']
#   - merge: kept 33 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-paytronix-prefix:
    description: API title should begin with "Paytronix".
    severity: warn
    given: $.info.title
    then:
      function: pattern
      functionOptions:
        match: ^Paytronix
  info-description-required:
    description: Info object must have a non-trivial description.
    severity: warn
    given: $.info
    then:
      field: description
      function: defined
  info-version-required:
    description: Info object must declare a version.
    severity: error
    given: $.info
    then:
      field: version
      function: defined
  info-contact-required:
    description: Info object should declare a contact.
    severity: info
    given: $.info
    then:
      field: contact
      function: defined
  openapi-version-3:
    description: Specs should target 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: $
    then:
      field: servers
      function: defined
  server-https:
    description: Server URLs must use HTTPS.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^https://
  server-description:
    description: Each server should have a description.
    severity: info
    given: $.servers[*]
    then:
      field: description
      function: defined
  operation-summary-required:
    description: Every operation must have a summary.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: summary
      function: defined
  operation-summary-title-case:
    description: Operation summaries must use Title Case (each word capitalized).
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].summary
    then:
      function: pattern
      functionOptions:
        match: ^([A-Z0-9][A-Za-z0-9]*)(\s+(?:[A-Z0-9][A-Za-z0-9]*|And|Or|By|For|To|In|Of|The|A|An))*$
  operation-description-required:
    description: Every operation must have a description.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: description
      function: defined
  operation-operationid-required:
    description: Every operation must have an operationId.
    severity: error
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: operationId
      function: defined
  operation-operationid-camelcase:
    description: operationId must 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 start with a known verb prefix.
    severity: info
    given: $.paths[*][get,post,put,delete,patch].operationId
    then:
      function: pattern
      functionOptions:
        match: ^(get|list|create|update|delete|add|redeem|sell|reload|recharge|activate|register|request|search|compute|post|change|query|balance|reverse|exchange|cash)
  operation-tags-required:
    description: Every operation must declare at least one tag.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: tags
      function: truthy
  operation-microcks-extension:
    description: Each operation should carry an x-microcks-operation extension for mock compatibility.
    severity: info
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: x-microcks-operation
      function: defined
  tags-global-defined:
    description: A global tags array must be defined.
    severity: warn
    given: $
    then:
      field: tags
      function: truthy
  tag-description:
    description: Each global tag should have a description.
    severity: info
    given: $.tags[*]
    then:
      field: description
      function: defined
  tag-title-case:
    description: Tag names must use Title Case.
    severity: warn
    given: $.tags[*].name
    then:
      function: pattern
      functionOptions:
        match: ^[A-Z][A-Za-z0-9]*(\s+[A-Z][A-Za-z0-9]*)*$
  parameter-description-required:
    description: Every parameter must have a description.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].parameters[*]
    then:
      field: description
      function: defined
  parameter-schema-typed:
    description: Every parameter schema must declare a type.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].parameters[*].schema
    then:
      field: type
      function: defined
  parameter-camelcase:
    description: Query and path parameter names should be camelCase (PXS) or snake_case (Open Dining search).
    severity: info
    given: $.paths[*][get,post,put,delete,patch].parameters[*].name
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-zA-Z0-9_]*$
  request-body-json:
    description: Request bodies should provide an application/json media type.
    severity: warn
    given: $.paths[*][post,put,patch].requestBody.content
    then:
      field: application/json
      function: defined
  request-body-schema:
    description: Request body JSON media type must reference a schema.
    severity: warn
    given: $.paths[*][post,put,patch].requestBody.content.application/json
    then:
      field: schema
      function: truthy
  response-2xx-required:
    description: Every operation must define a 2xx success response.
    severity: error
    given: $.paths[*][get,post,put,delete,patch].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
          - required:
            - '200'
          - required:
            - '201'
          - required:
            - '204'
  response-description-required:
    description: Every response must have a description.
    severity: warn
    given: $.paths[*][get,post,put,delete,patch].responses[*]
    then:
      field: description
      function: defined
  response-json-content:
    description: 2xx responses should provide application/json content.
    severity: info
    given: $.paths[*][get,post,put,delete,patch].responses[200,201].content
    then:
      field: application/json
      function: defined
  schema-property-typed:
    description: Schema properties should declare a type, $ref, or composition.
    severity: info
    given: $.components.schemas[*].properties[*]
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
          - required:
            - type
          - required:
            - $ref
          - required:
            - allOf
          - required:
            - oneOf
          - required:
            - anyOf
          - required:
            - additionalProperties
  schema-property-camelcase:
    description: Schema property names should be camelCase (PXS convention).
    severity: info
    given: $.components.schemas[*].properties.*~
    then:
      function: pattern
      functionOptions:
        match: ^[a-z][a-zA-Z0-9_]*$
  security-schemes-defined:
    description: components.securitySchemes should be defined where the API requires auth.
    severity: info
    given: $.components
    then:
      field: securitySchemes
      function: defined
  security-scheme-described:
    description: Each security scheme should have a description.
    severity: info
    given: $.components.securitySchemes[*]
    then:
      field: description
      function: defined
  get-no-request-body:
    description: GET operations must not declare a request body.
    severity: error
    given: $.paths[*].get
    then:
      field: requestBody
      function: undefined
  delete-no-request-body:
    description: DELETE operations should not declare a request body.
    severity: warn
    given: $.paths[*].delete
    then:
      field: requestBody
      function: undefined
  path-params-casing:
    description: Path parameters should be camelCase (the dominant convention in this API).
    severity: warn
    given: $.paths[*].parameters[?(@.in=='path')].name
    then:
      function: casing
      functionOptions:
        type: camel
  query-params-casing:
    description: Query parameters should be camelCase (the dominant convention in this API).
    severity: info
    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 (ErrorReply) should be defined for error payloads.
    severity: warn
    given: $.components.schemas
    then:
      field: ErrorReply
      function: truthy
  no-empty-descriptions:
    description: Descriptions must not be empty strings.
    severity: warn
    given: $..description
    then:
      function: truthy