University of Twente API Rules

# authorship: generated by API Evangelist tooling for the university pipeline.
# generated: '2026-09-01'
# method: generated
# source: openapi/_original/university-of-twente-energy-api-openapi.json
# x-operator: institution
#
# university-of-twente — OpenAPI Spectral ruleset
# Plain Spectral, built-in functions only. Rules measured from this API's OWN conventions,
# not from a house style, so the ruleset describes what the University of Twente Energy API
# already does and names the four places it does not.
#
# Measured on the harvested contract (3 operations, 9 component schemas):
#   operation-has-summary .......... 3/3   (100%) -> enforce
#   operation-has-tags ............. 3/3   (100%) -> enforce
#   response-has-description ....... 8/8   (100%) -> enforce
#   operation-declares-503 ......... 3/3   (100%) -> enforce, this API's own convention
#   property-name-casing ........... 27/27 camelCase (100%) -> enforce
#   schema-closed .................. 8/9   (89%)  -> warn
#   operation-has-operationId ...... 0/3   (0%)   -> GAP, warn
#   parameter-has-description ...... 5/7   (71%)  -> GAP, warn
#   root-declares-servers .......... absent -> GAP, error (the base URL is only knowable
#                                    from where the document is served)
#   response-has-example ........... 0     -> GAP, info
rules:
  operation-has-summary:
    description: Every operation should carry a summary. This API does, on all three.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy
  operation-has-tags:
    description: Every operation should be tagged. This API tags all three (Dashboard, Energy).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy
  response-has-description:
    description: Every declared response should describe what it means. This API describes all eight.
    severity: warn
    given: $.paths[*][*].responses[*]
    then:
      field: description
      function: truthy
  operation-declares-503:
    description: >-
      Every operation should declare 503 for the metering database being unreachable. This is the
      API's own convention — all three operations declare it — and it is worth holding onto.
    severity: info
    given: $.paths[*][get]
    then:
      field: responses.503
      function: truthy
  property-name-casing:
    description: Schema property names are camelCase throughout (27/27). Keep them that way.
    severity: warn
    given: $.components.schemas[*].properties[*]~
    then:
      function: pattern
      functionOptions:
        match: '^[a-z]+([A-Z][a-z0-9]*)*$'
  schema-closed:
    description: >-
      Component schemas should set additionalProperties false. Eight of nine do; ProblemDetails
      is the exception and it is the schema this API does not actually return.
    severity: info
    given: $.components.schemas[*]
    then:
      field: additionalProperties
      function: defined
  operation-has-operationid:
    description: >-
      GAP. No operation declares an operationId, so no generated client can name a method and no
      agent can address an operation by identifier. Three identifiers would close this.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
  parameter-has-description:
    description: >-
      GAP. Five of seven parameters are described; `corrected` and `co2` carry empty descriptions
      even though both change the meaning of every returned value.
    severity: warn
    given: $.paths[*][*].parameters[*]
    then:
      field: description
      function: truthy
  root-declares-servers:
    description: >-
      GAP. The document declares no servers[]. The base URL is recoverable only from the fact that
      the document happens to be served from energyapi.utwente.nl — the contract itself does not
      say where the API lives, which is the single defect most likely to break a machine consumer.
    severity: error
    given: $
    then:
      field: servers
      function: truthy
  root-declares-tags:
    description: >-
      GAP. Operations are tagged but the root tags[] array is absent, so the two tag names carry
      no descriptions.
    severity: info
    given: $
    then:
      field: tags
      function: truthy
  info-contact-is-institutional:
    description: >-
      GAP, recorded rather than machine-checkable. info.contact names Realised, the contracted
      developer (energydata@realised.nl), not the university. The university's own published
      contact for this platform is sustainability@utwente.nl. A consumer reading the contract is
      routed away from the operator.
    severity: info
    given: $.info
    then:
      field: contact
      function: truthy