University of California, San Francisco API Rules

x-name: UCSF API Governance Rules
description: >-
  Spectral-style ruleset expressing the governance expectations UCSF's own institution-operated
  contracts should meet, written against the OpenAPI descriptions in openapi/. Generated by API
  Evangelist; UCSF publishes no governance ruleset. Uses built-in Spectral functions only.
x-generated: '2026-08-19'
x-method: generated
x-operator: institution
x-source:
  - openapi/ucsf-profiles-json-openapi.yml
  - openapi/ucsf-industry-documents-solr-openapi.yml
x-ruleset:
  extends: []
  rules:
    ucsf-info-contact:
      description: Every UCSF contract must name a contactable UCSF unit.
      given: $.info
      severity: error
      then:
        field: contact
        function: truthy
    ucsf-info-description-length:
      description: The contract description must be substantive, not a title restated.
      given: $.info.description
      severity: warn
      then:
        function: length
        functionOptions:
          min: 200
    ucsf-server-must-be-ucsf-owned:
      description: >-
        Server URLs on a UCSF contract must sit under a ucsf.edu host. This is the operator
        check — a contract whose servers[] points anywhere else belongs to a vendor, not to UCSF.
      given: $.servers[*].url
      severity: error
      then:
        function: pattern
        functionOptions:
          match: '^https://[a-zA-Z0-9.-]+\.ucsf\.edu(/|$)'
    ucsf-operator-declared:
      description: Every contract must declare who operates the service it describes.
      given: $.info
      severity: error
      then:
        field: x-operator
        function: truthy
    ucsf-provenance-declared:
      description: Every contract must declare how API Evangelist came to hold it.
      given: $.info
      severity: error
      then:
        field: x-provenance
        function: truthy
    ucsf-operation-id:
      description: Every operation needs a stable operationId.
      given: $.paths[*][get,post,put,patch,delete]
      severity: error
      then:
        field: operationId
        function: truthy
    ucsf-operation-tagged:
      description: Every operation must be tagged so it can be split and catalogued.
      given: $.paths[*][get,post,put,patch,delete]
      severity: error
      then:
        field: tags
        function: truthy
    ucsf-error-responses-described:
      description: >-
        Public UCSF APIs must describe their failure modes. Both surfaces were found to have
        undocumented or prose-only error contracts.
      given: $.paths[*][get,post,put,patch,delete].responses
      severity: warn
      then:
        field: '400'
        function: truthy
    ucsf-parameter-description:
      description: Every parameter must be described — the IDL Solr query syntax is not self-evident.
      given: $.paths[*][get,post,put,patch,delete].parameters[*]
      severity: warn
      then:
        field: description
        function: truthy
    ucsf-deprecated-must-explain:
      description: >-
        A deprecated parameter must say what replaces it. UCSF Profiles does this in prose and
        in-band via api_notes; the rule keeps that behaviour from regressing.
      given: $.paths[*][get,post,put,patch,delete].parameters[?(@.deprecated == true)]
      severity: warn
      then:
        field: description
        function: truthy
x-findings:
  - rule: ucsf-server-must-be-ucsf-owned
    result: pass
    detail: Both contracts serve from *.ucsf.edu (api.profiles.ucsf.edu, solr.idl.ucsf.edu).
  - rule: ucsf-error-responses-described
    result: pass-in-artifact-only
    detail: >-
      The 400/403/404 responses present in these contracts were established by API Evangelist
      probing, not by UCSF documentation. UCSF documents error handling for Profiles in prose
      and documents nothing for the IDL Solr API.