SimpleLegal · API Governance Rules

SimpleLegal API Rules

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

8 Rules warn 5 info 3

View Rules File View on GitHub

Rule Categories

simplelegal

Rules

warn

simplelegal-summary-title-case

Operation summaries must use Title Case.

$.paths[*][*].summary

warn

simplelegal-operationid-kebab-case

OperationIds must use kebab-case naming.

$.paths[*][*].operationId

info

simplelegal-pagination-params

Collection GET endpoints should support page and page_size parameters.

$.paths[?([email protected](/{.*}/))].get.parameters[*].name

warn

simplelegal-basic-auth

API must use HTTP Basic authentication.

$.components.securitySchemes[*].scheme

info

simplelegal-patch-update

Update operations should prefer PATCH over PUT.

$.paths[*].put.operationId

warn

simplelegal-json-responses

All responses should return application/json.

$.paths[*][*].responses[?(@property >= '200')].content

info

simplelegal-error-responses

Operations should document authentication and not-found error responses.

$.paths[*][*].responses

warn

simplelegal-descriptions-required

All paths and operations must have descriptions.

$.paths[*][*]$.info

Spectral Ruleset

extends: "spectral:oas"
rules:
  simplelegal-summary-title-case:
    description: Operation summaries must use Title Case.
    message: "Summary '{{value}}' must be in Title Case."
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*([ ][A-Z][a-zA-Z0-9]*)*$"

  simplelegal-operationid-kebab-case:
    description: OperationIds must use kebab-case naming.
    message: "OperationId '{{value}}' must use kebab-case."
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"

  simplelegal-pagination-params:
    description: Collection GET endpoints should support page and page_size parameters.
    message: "Collection endpoint should support pagination parameters."
    severity: info
    given: "$.paths[?([email protected](/{.*}/))].get.parameters[*].name"
    then:
      function: enumeration
      functionOptions:
        values:
          - page
          - page_size
          - status
          - matter_id
          - vendor_id
          - type
          - active

  simplelegal-basic-auth:
    description: API must use HTTP Basic authentication.
    message: "API should use HTTP Basic authentication."
    severity: warn
    given: "$.components.securitySchemes[*].scheme"
    then:
      function: enumeration
      functionOptions:
        values:
          - basic

  simplelegal-patch-update:
    description: Update operations should prefer PATCH over PUT.
    message: "Update operations should use PATCH for partial updates."
    severity: info
    given: "$.paths[*].put.operationId"
    then:
      function: falsy

  simplelegal-json-responses:
    description: All responses should return application/json.
    message: "Response should include application/json content type."
    severity: warn
    given: "$.paths[*][*].responses[?(@property >= '200')].content"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - "application/json"

  simplelegal-error-responses:
    description: Operations should document authentication and not-found error responses.
    message: "Operation should document error responses (401, 404)."
    severity: info
    given: "$.paths[*][*].responses"
    then:
      function: truthy

  simplelegal-descriptions-required:
    description: All paths and operations must have descriptions.
    message: "{{property}} is missing a description."
    severity: warn
    given:
      - "$.paths[*][*]"
      - "$.info"
    then:
      field: description
      function: truthy