overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Green Button ESPI specification (Hydro Ottawa profile)
  version: 1.0.0
x-generated: '2026-07-27'
x-method: generated
x-source: openapi/hydro-ottawa-green-button-espi-openapi.yml
x-note: >-
  The extended document is authored by the Green Button Alliance, not by Hydro Ottawa.
  This overlay carries the API Evangelist annotations for the Hydro Ottawa profile
  without mutating the harvested specification: provenance, the ESPI version gap
  (the document describes ESPI 4.0 while Ontario O. Reg. 633/21 mandates ESPI v3.3),
  the fact that servers[] points at the GBA sandbox rather than any Hydro Ottawa host,
  and the access gate a developer actually faces.
extends: openapi/hydro-ottawa-green-button-espi-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-provider: hydro-ottawa
    x-apievangelist-profile: https://raw.githubusercontent.com/api-evangelist/hydro-ottawa/refs/heads/main/apis.yml
    x-apievangelist-spec-authorship: >-
      Green Button Alliance. Hydro Ottawa publishes no first-party OpenAPI and no ESPI
      base URI. This document is the family contract, not Hydro Ottawa's service.
    x-apievangelist-mandate: >-
      Ontario Regulation 633/21 (Energy Data) under the Electricity Act, 1998 compels
      covered Ontario electricity and natural gas distributors to implement Green Button
      Download My Data and Connect My Data to NAESB REQ.21 ESPI v3.3 and to certify with
      the Green Button Alliance.
    x-apievangelist-version-gap: >-
      This document declares ESPI 4.0. The Ontario mandate is ESPI v3.3. Do not assume
      the two are interchangeable when integrating with an Ontario distributor.
    x-apievangelist-access-gate: >-
      application-approval. Complete Hydro Ottawa third-party onboarding at
      https://ottawaonboarding.savagedata.com/ and certify with the Green Button Alliance
      at https://www.greenbuttonalliance.org/testing. Connection details are issued only
      after both. There is no self-serve signup and no sandbox from Hydro Ottawa.
- target: $.servers
  update:
    x-apievangelist-note: >-
      The single declared server is the Green Button Alliance sandbox, NOT a Hydro Ottawa
      host. No Hydro Ottawa ESPI base URI is published anywhere. api.hydroottawa.com
      resolves but returns HTTP 403 at root and 404 on every path probed on 2026-07-27.
- target: $.components.securitySchemes.oauth2
  update:
    x-apievangelist-note: >-
      The scopes object is empty in the source document; no scope names were invented.
      Hydro Ottawa publishes no scope reference and no anonymously served OpenID Connect
      discovery document exists on any Hydro Ottawa or Savage Data host.
- target: $.paths['/espi/1_1/resource/UsagePoint'].get
  update:
    x-apievangelist-note: >-
      Pagination in ESPI is Atom-style: start-index (1-indexed) plus max-results, with
      published-min/published-max and updated-min/updated-max RFC 3339 time filters and a
      depth control. Responses are application/atom+xml feeds, not JSON.
- target: $.paths['/espi/1_1/resource/Batch/Bulk/{bulkId}'].get
  update:
    x-apievangelist-note: >-
      Bulk transfer is the asynchronous path — a 202 Accepted is a normal, expected
      outcome here and the client must be prepared to poll rather than treat it as an error.