Elhub API Rules

# authorship: generated by API Evangelist tooling (derive-rules.py, 2026-10-09). x-method: generated
# Every rule below was MEASURED against Elhub's own contract before it was written; a rule is present only
# when the contract satisfies it at 80% or more. Severity: 100% -> error, >= 90% -> warn, else info.
# Provenance:
#   - operation-has-operationid: 98%
#   - operationid-casing-snake: 86%
#   - operation-has-summary: 100%
#   - operation-has-description: 92%
#   - operation-has-tags: 97%
#   - operation-has-success-response: 97%
#   - operation-declares-4xx: 98%
#   - operation-declares-401-or-403: 93%
#   - operation-secured: 90%
#   - path-no-trailing-slash: 100%
#   - path-params-in-braces: 100%
#   - servers-https: 89%
#   - write-declares-request-body: 100%
#   - schema-has-description: 90%
#   - info-has-description: 100%
#   - info-has-contact-or-terms: 100%
x-method: generated
x-generator: derive-rules.py
x-generated: '2026-10-09'
x-source:
- openapi/elhub-access-api-openapi.yml
- openapi/elhub-data-export-api-openapi.yml
- openapi/elhub-energy-data-api-openapi.yml
- openapi/elhub-flex-information-system-auth-api-openapi.yml
- openapi/elhub-flex-information-system-grid-api-openapi.yml
extends:
- - spectral:oas
  - recommended
formats:
- oas3
rules:
  operation-has-operationid:
    description: 'Every operation declares an operationId (measured: 98% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  operationid-casing-snake:
    description: 'operationIds are snakeCase (measured: 86% of this contract)'
    severity: info
    given: $.paths[*][get,post,put,patch,delete].operationId
    then:
      function: casing
      functionOptions:
        type: snake
  operation-has-summary:
    description: 'Every operation has a summary (measured: 100% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy
  operation-has-description:
    description: 'Every operation has a description (measured: 92% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: description
      function: truthy
  operation-has-tags:
    description: 'Every operation is tagged (measured: 97% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy
  operation-has-success-response:
    description: 'Every operation declares a 2xx response (measured: 97% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            ^2\d\d$: {}
          minProperties: 1
  operation-declares-4xx:
    description: 'Every operation declares at least one 4xx response (measured: 98% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            ^4\d\d$: {}
          minProperties: 1
  operation-declares-401-or-403:
    description: 'Every operation declares 401 or 403 (measured: 93% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
          - required:
            - '401'
          - required:
            - '403'
  operation-secured:
    description: 'Every operation is covered by a security requirement (measured: 90% of this contract)'
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: security
      function: truthy
  path-no-trailing-slash:
    description: 'Paths carry no trailing slash (measured: 100% of this contract)'
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: ./$
  path-params-in-braces:
    description: 'Path parameters use {braces}, not :colon (measured: 100% of this contract)'
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: ':'
  servers-https:
    description: 'Servers are https (measured: 89% of this contract)'
    severity: info
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^(https://|\{)
  write-declares-request-body:
    description: 'POST and PUT declare a request body (measured: 100% of this contract)'
    severity: error
    given: $.paths[*][post,put]
    then:
      field: requestBody
      function: truthy
  schema-has-description:
    description: 'Every component schema carries a title or description (measured: 90% of this contract)'
    severity: info
    given: $.components.schemas[*]
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
          - required:
            - description
          - required:
            - title
  info-has-description:
    description: 'The contract''s info block carries a description (measured: 100% of this contract)'
    severity: error
    given: $.info
    then:
      field: description
      function: truthy
  info-has-contact-or-terms:
    description: 'The contract''s info block names a contact or terms of service (measured: 100% of this contract)'
    severity: error
    given: $.info
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
          - required:
            - contact
          - required:
            - termsOfService