Indian Institute of Technology Bombay API Rules

# authorship: generated by an API Evangelist university-pipeline pass, 2026-08-30.
# An unmarked file is NOT assumed to be ours.
x-method: derived
x-source: openapi/iit-bombay-instiapp-api-openapi.yml
x-operator: institution
# IIT Bombay — Spectral ruleset measured from this institution's own contract.
#
# Measured on 2026-08-30 against the institution's published specification
# (112 paths / 164 operations / 37 schemas):
#   - operationId present ............ 164/164 (100%)  -> enforced at error
#   - description or summary ......... 99/164  (60%)   -> warn, not error
#   - schema description ............. 0/37    (0%)    -> warn only; not this API's convention
#   - 4xx/5xx response declared ...... 0/164   (0%)    -> warn; the real contract gap
#   - property casing ................ snake_case/lowercase 368, camelCase 2 -> snake enforced
#   - path segment casing ............ lowercase 150, kebab 31, camel 5      -> camel discouraged
#   - trailing slash on path .......... 32/112 (29%)   -> warn on inconsistency only
rules:

  operation-has-operationId:
    description: Every operation should carry an operationId. This API already does, 164/164.
    severity: error
    given: $.paths[*][get,put,post,delete,patch]
    then:
      field: operationId
      function: truthy

  operation-described:
    description: >-
      Operations should carry a description or summary. 99 of 164 do; the 65 that do not are
      mostly autogenerated CRUD routes.
    severity: warn
    given: $.paths[*][get,put,post,delete,patch]
    then:
      field: description
      function: truthy

  operation-declares-error-response:
    description: >-
      Every operation should declare at least one 4xx response. None of the 164 currently do,
      while the deployed API returns 401, 403 and 404 in practice. This is the single largest
      contract gap in IIT Bombay's public footprint.
    severity: warn
    given: $.paths[*][get,put,post,delete,patch].responses
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
          - required: ['400']
          - required: ['401']
          - required: ['403']
          - required: ['404']

  property-name-snake-case:
    description: Property names should be snake_case or a single lowercase word — this API's convention at 368/370.
    severity: warn
    given: $.components.schemas[*].properties
    then:
      field: '@key'
      function: casing
      functionOptions:
        type: snake

  path-segment-not-camel-case:
    description: >-
      Path segments should be lowercase or kebab-case. Five segments break this
      (/alumniLogin, /alumniOTP, /getEncr, /getUserMess, /resendAlumniOTP) against 181 that do not.
    severity: warn
    given: $.paths
    then:
      field: '@key'
      function: pattern
      functionOptions:
        notMatch: '/[a-z0-9-]*[A-Z]'

  info-contact-email:
    description: info.contact.email should be present — it is what makes an operator attributable.
    severity: error
    given: $.info.contact
    then:
      field: email
      function: truthy

  servers-declared:
    description: >-
      servers[] must be present and non-empty. Recorded explicitly because a per-tag refine split
      is known to drop the top-level servers block, which would erase the one piece of evidence
      that this contract is the institution's and not a vendor's.
    severity: error
    given: $
    then:
      field: servers
      function: truthy