API Evangelist enhancements for OEB Regulatory Document Search

overlay: 1.0.0
info:
  title: API Evangelist enhancements for OEB Regulatory Document Search
  version: 1.0.0
extends: openapi/ontario-energy-board-rds-openapi.yml
x-generated: '2026-07-27'
x-method: generated
x-source: >-
  Live anonymous probes of https://www.rds.oeb.ca/CMWebDrawer on 2026-07-27 plus the live search-clause
  vocabulary at /Help/WDSearchClauseDefJS
x-note: >-
  The base document is itself generated by API Evangelist, because the Ontario Energy Board publishes no
  specification for this surface. This overlay records the enhancements that are OUR editorial layer
  rather than observed protocol facts - provenance flags, the pointer to the derived query vocabulary,
  the read-only/agent-safety annotations and the error-handling warnings an agent must carry. Keeping
  them in an overlay means the generated base can be regenerated from probes without losing them.
actions:
  - target: $.info
    update:
      x-api-evangelist-provenance:
        generated_by: API Evangelist enrichment pipeline
        method: generated-from-live-probes
        probed: '2026-07-27'
        published_by_provider: false
        supported_by_provider: false
        warning: >-
          The OEB has never documented this interface. It is the default JSON projection of Micro Focus /
          OpenText Content Manager WebDrawer and may change or be withdrawn without notice.
  - target: $.info
    update:
      x-vocabulary: vocabulary/ontario-energy-board-rds-search-clauses.yml
      x-error-catalog: errors/ontario-energy-board-problem-types.yml
      x-conventions: conventions/ontario-energy-board-conventions.yml
      x-data-model: data-model/ontario-energy-board-data-model.yml
  - target: $.paths.*.get
    update:
      x-read-only: true
      x-consequence: none
      x-agent-safe: true
      x-authentication: none
  - target: $.paths['/Record'].get
    update:
      x-response-validation-required: >-
        HTTP 200 does not mean the query succeeded. Read SearchTitle on every response - an unknown
        clause or a wildcard used with '=' returns 200 with an empty Results array and the reason in
        that field.
      x-pagination:
        style: offset
        page_size_param: pageSize
        offset_param: start
        offset_base: 1
        total_field: TotalResults
        more_field: HasMoreItems
      x-clause-source: https://www.rds.oeb.ca/CMWebDrawer/Help/WDSearchClauseDefJS?trimType=Record
  - target: $.paths['/Record/{uri}'].get
    update:
      x-status: broken-for-anonymous-callers
      x-workaround: >-
        Take metadata from the search hit and fetch bytes from /Record/{uri}/File/document; record
        detail returns HTTP 500 TrimException (TrimErrorCode 22760) to anonymous callers.
  - target: $.paths['/Record/{uri}/File/document'].get
    update:
      x-content-types-observed:
        - application/pdf
      x-record-extensions-observed:
        - PDF
        - MSG
        - DOC
        - XLS
      x-note: >-
        Check RecordExtension on the search hit before assuming PDF; correspondence is frequently MSG.
  - target: $.components.schemas.TrimDateTime
    update:
      x-null-sentinel:
        when: 'IsClear is true'
        value: '0001-01-01T00:00:00.0000000Z'
        guidance: Treat as null. Do not parse or store the year 1 as a real date.