University of Maryland College Park API Rules

# generated: '2026-08-30'
# method: derived
# source: openapi/university-of-maryland-college-park-libraries-website-tools-openapi.yml
# x-operator: institution
#
# Spectral ruleset for the University of Maryland's one institution-operated OpenAPI, the
# UMD Libraries Website Tools API. Every rule below was written against a defect actually
# present in, or a convention actually held by, that contract as harvested on 2026-08-30.
# Built-in Spectral functions only.
rules:
  umd-info-title-not-framework-default:
    description: >-
      info.title must name the service. The harvested contract carries the FastAPI default
      "FastAPI", which makes the document unattributable once it leaves its host.
    message: '{{description}}'
    severity: error
    given: $.info
    then:
      field: title
      function: pattern
      functionOptions:
        notMatch: '^(FastAPI|Swagger|API|OpenAPI)$'

  umd-info-version-moved-off-default:
    description: >-
      info.version must not remain the framework default 0.1.0. UMD's contract has never
      bumped it, so consumers cannot tell one deployment from another.
    message: '{{description}}'
    severity: warn
    given: $.info
    then:
      field: version
      function: pattern
      functionOptions:
        notMatch: '^0\.1\.0$'

  umd-servers-absolute:
    description: >-
      servers[].url must be absolute. The harvested contract declares the relative
      "/api/libtools", which is only resolvable if you already know the host.
    message: '{{description}}'
    severity: error
    given: $.servers[*]
    then:
      field: url
      function: pattern
      functionOptions:
        match: '^https://'

  umd-info-contact-present:
    description: >-
      info.contact must be present. UMD Libraries publish a contact page on their Open Data
      site; the contract does not point at it.
    message: '{{description}}'
    severity: error
    given: $.info
    then:
      field: contact
      function: truthy

  umd-operation-has-summary:
    description: Every operation needs a human summary; the harvested summaries were method names.
    message: '{{description}}'
    severity: error
    given: $.paths[*][*]
    then:
      field: summary
      function: truthy

  umd-operation-has-description:
    description: Every operation needs a description beyond its summary.
    message: '{{description}}'
    severity: warn
    given: $.paths[*][*]
    then:
      field: description
      function: truthy

  umd-operation-tagged:
    description: Every operation must carry at least one tag; the harvested contract declared none.
    message: '{{description}}'
    severity: error
    given: $.paths[*][*]
    then:
      field: tags
      function: length
      functionOptions:
        min: 1

  umd-success-response-typed:
    description: >-
      A 200 must declare a schema. Eleven of the thirteen harvested operations return an
      untyped empty schema, so nothing about the payload is contractual.
    message: '{{description}}'
    severity: error
    given: $.paths[*][*].responses['200'].content['application/json']
    then:
      field: schema
      function: truthy

  umd-not-found-declared:
    description: >-
      404 must be declared. The service returns {"detail":"Not Found"} for any unknown path
      and the harvested contract never says so.
    message: '{{description}}'
    severity: warn
    given: $.paths[*][*].responses
    then:
      field: '404'
      function: truthy

  umd-parameter-described:
    description: >-
      Every parameter needs a description. The availability parameter is undocumented, and an
      empty value returns 500 rather than the declared 422.
    message: '{{description}}'
    severity: warn
    given: $.paths[*][*].parameters[*]
    then:
      field: description
      function: truthy

  umd-external-docs-present:
    description: >-
      The contract should point at the Open Data service page that documents it.
    message: '{{description}}'
    severity: warn
    given: $
    then:
      field: externalDocs
      function: truthy