Politecnico di Milano API Rules

# Generated by API Evangelist (pipeline-university) from live probes of the institution's own hosts.
# Politecnico di Milano — Spectral ruleset for the institution-operated contracts in this repo.
# Built-in functions only. Written by API Evangelist, not by the institution.
# generated: 2026-09-01 | method: generated | source: openapi/*.yml in this repository
---
extends: [[spectral:oas, recommended]]
rules:
  polimi-operator-declared:
    description: >-
      Every contract in this repository must declare who operates the thing it describes. A university is a
      federation of buyers; without info.x-operator a vendor's contract reads as the institution's.
    message: 'info.x-operator is required (institution | tenant | vendor | registry | federation)'
    severity: error
    given: $.info
    then:
      field: x-operator
      function: truthy
  polimi-operator-institution-only:
    description: Only institution-operated contracts belong in this repository's openapi/ directory.
    message: 'info.x-operator must be "institution" for a saved contract; tenant/vendor surfaces are apis.yml entries only'
    severity: error
    given: $.info.x-operator
    then:
      function: pattern
      functionOptions:
        match: '^institution$'
  polimi-operator-evidence:
    description: The operator verdict must name the evidence that produced it.
    message: 'info.x-operator-evidence is required alongside info.x-operator'
    severity: error
    given: $.info
    then:
      field: x-operator-evidence
      function: truthy
  polimi-provenance-block:
    description: >-
      An unmarked artifact is credited to the institution as if they published it. Every contract must carry
      x-provenance with generated, method and source.
    message: 'info.x-provenance must declare generated, method and source'
    severity: error
    given: $.info.x-provenance
    then:
      - field: generated
        function: truthy
      - field: method
        function: truthy
      - field: source
        function: truthy
  polimi-provenance-method-vocabulary:
    description: method must come from the controlled vocabulary.
    message: 'x-provenance.method must be one of searched, generated, derived, probed, none'
    severity: error
    given: $.info.x-provenance.method
    then:
      function: enumeration
      functionOptions:
        values: [ searched, generated, derived, probed, none ]
  polimi-server-on-own-domain:
    description: >-
      A saved contract's server must sit under polimi.it. A server on a vendor host is the misattribution this
      repository exists to prevent.
    message: 'servers[].url must be under a polimi.it host'
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: '^https://[a-z0-9.-]*polimi\.it'
  polimi-no-relative-servers:
    description: >-
      A relative or absent server makes the host-based operator check blind — the "hostless" class that let
      36 Elsevier Pure contracts pass as one university's own.
    message: 'servers must be present and absolute'
    severity: error
    given: $
    then:
      field: servers
      function: truthy
  polimi-operation-described:
    description: Every operation needs a summary and a description a reader can act on.
    severity: warn
    given: $.paths[*][get,put,post,delete,patch]
    then:
      - field: summary
        function: truthy
      - field: description
        function: truthy
  polimi-operation-id:
    description: Every operation needs an operationId.
    severity: error
    given: $.paths[*][get,put,post,delete,patch]
    then:
      field: operationId
      function: truthy
  polimi-response-examples:
    description: >-
      Responses on these surfaces should carry a real captured example — every example in this repository is a
      live payload in examples/, not an invented one.
    severity: warn
    given: $.paths[*][get].responses[*].content[*]
    then:
      field: examples
      function: truthy
  polimi-license-declared:
    description: >-
      The open data is CC BY 4.0 per the DCAT catalogue; where a licence is known it must be stated.
    severity: warn
    given: $.info
    then:
      field: license
      function: truthy