1_oadr3.0.1.yaml

openapi: 3.0.0
servers:
  - description: base path
    url: http://localhost:8081/openadr3/3.0.1
info:
  title: OpenADR 3 API
  version: "3.0.1"
  description: |
    The OpenADR 3 API supports energy retailer to energy customer Demand Response programs.
    See OpenADR 3 User Guide and Defintions for detailed descriptions of usage.
    The API includes the following capabilities and operations:

    __Manage programs:__

    * Create/Update/Delete a program
    * Search programs

    __Manage events:__

    * Create/Update/Delete an event
    * Search events

    __Manage reports:__

    * Create/Update/Delete a report
    * Search reports

    __Manage subscriptions:__

    * Create/Update/Delete subscriptions to programs, events, and reports
    * Search subscriptions
    * Subscriptions allows clients to register a callback URL (webhook) to be notified
      on the change of state of a resource

    __Manage vens:__

    * Create/Update/Delete vens and ven resources
    * Search ven and ven resources

    __Manage tokens:__

    * Obtain an access token
    * This endpoint is provided as a convenience and may be neglected in a commercial implementation
  contact:
    email: frank@pajaritotech.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
paths:
  /programs:
    get:
      tags:
        - programs
      summary: searches all programs
      operationId: searchAllPrograms
      description: |
        List all programs known to the server.
        May filter results by targetType and targetValues as query params.
        Use skip and pagination query params to limit response size.
      security:
        - oAuth2ClientCredentials: [read_all]
        # bearerAuth added here and elsewhere to support RI /ui service. See RI README for description of /ui
        - bearerAuth: []
      parameters:
      - name: targetType
        in: query
        description: Indicates targeting type, e.g. GROUP
        required: false
        schema:
          type: string
      - name: targetValues
        in: query
        description: List of target values, e.g. group names
        required: false
        schema:
          type: array
          items:
            type: string
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 50
          minimum: 0
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/program'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
        - programs
      summary: create a program
      operationId: createProgram
      description: Create a new program in the server.
      security:
        - oAuth2ClientCredentials: [write_programs]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/program'
        description: program item to add.
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/program'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /programs/{programID}:
    parameters:
      - name: programID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        required: true
        description: Object ID of the program object.
    get:
      tags:
        - programs
      summary: searches programs by program ID
      operationId: searchProgramByProgramId
      description:  |
        Fetch the program specified by the programID in path.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/program'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    put:
      tags:
        - programs
      summary: update a program
      operationId: updateProgram
      description: Update an existing program with the programID in path.
      security:
        - oAuth2ClientCredentials: [write_programs]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/program'
        description: program item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/program'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    delete:
      tags:
        - programs
      summary: delete a program
      operationId: deleteProgram
      description: Delete an existing program with the programID in path.
      security:
        - oAuth2ClientCredentials: [write_programs]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/program'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /reports:
    get:
      tags:
        - reports
      summary: searches all reports
      operationId: searchAllReports
      description: |
        List all reports known to the server.
        May filter results by programID, eventID,  and clientName as query param.
        Use skip and pagination query params to limit response size.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      parameters:
      - name: programID
        in: query
        schema:
          $ref: '#/components/schemas/objectID'
        required: false
        description: filter results to reports with programID.
        example: program-999
      - name: eventID
        in: query
        schema:
          $ref: '#/components/schemas/objectID'
        required: false
        description: filter results to reports with eventID.
        example: event-999
      - name: clientName
        in: query
        schema:
          type: string
        required: false
        description: filter results to reports with clientName.
        example: 999
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 50
          minimum: 0
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/report'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
        - reports
      summary: add a report
      operationId: createReport
      description: Create a new report in the server.
      security:
        - oAuth2ClientCredentials: [write_reports]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/report'
        description: report item to add.
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if identical report exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /reports/{reportID}:
    parameters:
      - name: reportID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        required: true
        description: object ID of a report.
    get:
      tags:
        - reports
      summary: searches reports by reportID
      operationId: searchReportsByReportID
      description: |
        Fetch the report specified by the reportID in path.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    put:
      tags:
        - reports
      summary: update a report
      operationId: updateReport
      description: Update the report specified by the reportID in path.
      security:
        - oAuth2ClientCredentials: [write_reports]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/report'
        description: Report item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    delete:
      tags:
        - reports
      summary: delete a report
      operationId: deleteReport
      description: Delete the report specified by the reportID in path.
      security:
        - oAuth2ClientCredentials: [write_reports]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /events:
    get:
      tags:
        - events
      summary: searches all events
      operationId: searchAllEvents
      description: |
        List all events known to the server.
        May filter results by programID query param.
        May filter results by targetType and targetValues as query params.
        Use skip and pagination query params to limit response size.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      parameters:
      - name: programID
        in: query
        schema:
          $ref: '#/components/schemas/objectID'
        required: false
        description: filter results to events with programID.
        example: program-999
      - name: targetType
        in: query
        description: Indicates targeting type, e.g. GROUP
        required: false
        schema:
          type: string
      - name: targetValues
        in: query
        description: List of target values, e.g. group names
        required: false
        schema:
          type: array
          items:
            type: string
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 50
          minimum: 0
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
        - events
      summary: create an event
      operationId: createEvent
      description: Create a new event in the server.
      security:
        - oAuth2ClientCredentials: [write_events]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/event'
        description: Event item to add.
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if event with  same name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /events/{eventID}:
    parameters:
      - name: eventID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        description: object ID of event.
        required: true
    get:
      tags:
        - events
      summary: search events by ID
      operationId: searchEventsByID
      description: |
        Fetch event associated with the eventID in path.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    put:
      tags:
        - events
      summary: update an event
      operationId: updateEvent
      description: Update the event specified by the eventID in path.
      security:
        - oAuth2ClientCredentials: [write_events]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/event'
        description: event item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    delete:
      tags:
        - events
      summary: delete an event
      operationId: deleteEvent
      description: |
        Delete the event specified by the eventID in path.
      security:
        - oAuth2ClientCredentials: [write_events]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /subscriptions:
    get:
      tags:
        - subscriptions
      summary: search subscriptions
      operationId: searchSubscriptions
      description: |
        List all subscriptions.
        May filter results by programID and clientName as query params.
        May filter results by targetType and targetValues as query params.
        May filter results by objects as query param. See objectTypes schema.
        Use skip and pagination query params to limit response size.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      parameters:
      - name: programID
        in: query
        schema:
          $ref: '#/components/schemas/objectID'
        description: filter results to subscriptions with programID.
        required: false
      - name: clientName
        in: query
        schema:
          type: string
        description: filter results to subscriptions with clientName.
        required: false
      - name: targetType
        in: query
        description: Indicates targeting type, e.g. GROUP
        required: false
        schema:
          type: string
      - name: targetValues
        in: query
        description: List of target values, e.g. group names
        required: false
        schema:
          type: array
          items:
            type: string
      - name: objects
        in: query
        description: list of objects to subscribe to.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/objectTypes'
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        style: form
        explode: true
        schema:
          minimum: 0
          type: integer
          format: int32
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 0
          type: integer
          format: int32
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
        - subscriptions
      summary: create subscription
      operationId: createSubscription
      description: Create a new subscription.
      security:
        - oAuth2ClientCredentials: [write_subscriptions]
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscription'
      callbacks:   # Callback definition
        notifyEvent:   # callback Event name
          '{$request.body#/callbackUrl}':   # The callback URL. Refers to the passed URL
            post:
              requestBody:   # Contents of the callback message
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/notification'
              responses:   # Expected responses to the callback message
                '200':
                  description: Your server returns this code if it accepts the callback.
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if identical object already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /subscriptions/{subscriptionID}:
    parameters:
      - name: subscriptionID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        description: object ID of the associated subscription.
        required: true
    get:
      tags:
        - subscriptions
      summary: search subscriptions by ID
      operationId: searchSubscriptionByID
      description: Return the subscription specified by subscriptionID specified in path.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    put:
      tags:
        - subscriptions
      summary: update  subscription
      operationId: updateSubscription
      description: Update the subscription specified by subscriptionID specified in path.
      security:
        - oAuth2ClientCredentials: [write_subscriptions]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscription'
        description: subscription item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    delete:
      tags:
        - subscriptions
      summary: delete  subscription
      operationId: deleteSubscription
      description: Delete the subscription specified by subscriptionID specified in path.
      security:
        - oAuth2ClientCredentials: [write_subscriptions]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /vens:
    get:
      tags:
        - vens
      summary: search vens
      operationId: searchVens
      description: |
        List all vens.
        May filter results by venName as query param.
        May filter results by targetType and targetValues as query params.
        Use skip and pagination query params to limit response size.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      parameters:
      - name: venName
        in: query
        description: Indicates ven objects w venName
        required: false
        schema:
          type: string
      - name: targetType
        in: query
        description: Indicates targeting type, e.g. GROUP
        required: false
        schema:
          type: string
      - name: targetValues
        in: query
        description: List of target values, e.g. group names
        required: false
        schema:
          type: array
          items:
            type: string
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        style: form
        explode: true
        schema:
          minimum: 0
          type: integer
          format: int32
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 0
          type: integer
          format: int32
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ven'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
        - vens
      summary: create ven
      operationId: createVen
      description: Create a new ven.
      security:
        - oAuth2ClientCredentials: [write_vens]
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ven'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ven'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if ven with same venIdentifier already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /vens/{venID}:
    parameters:
      - name: venID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        description: object ID of ven.
        required: true
    get:
      tags:
        - vens
      summary: search vens by ID
      operationId: searchVenByID
      description: Return the ven specified by venID specified in path.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ven'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    put:
      tags:
        - vens
      summary: update  ven
      operationId: updateVen
      description: Update the ven specified by venID specified in path.
      security:
        - oAuth2ClientCredentials: [write_vens]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ven'
        description: ven item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ven'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    delete:
      tags:
        - vens
      summary: delete  ven
      operationId: deleteVen
      description: Delete the ven specified by venID specified in path.
      security:
        - oAuth2ClientCredentials: [write_vens]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ven'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /vens/{venID}/resources:
    parameters:
      - name: venID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        description: Numeric ID of ven.
        required: true
    get:
      tags:
        - vens
      summary: search ven resources
      operationId: searchVenResources
      description: |
        List all ven resources associated with ven with specified venID.
        May filter results by resourceName as query params.
        May filter results by targetType and targetValues as query params.
        Use skip and pagination query params to limit response size.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      parameters:
      - name: resourceName
        in: query
        description: Indicates resource objects with resourceName
        required: false
        schema:
          type: string
      - name: targetType
        in: query
        description: Indicates targeting type, e.g. GROUP
        required: false
        schema:
          type: string
      - name: targetValues
        in: query
        description: List of target values, e.g. group names
        required: false
        schema:
          type: array
          items:
            type: string
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        style: form
        explode: true
        schema:
          minimum: 0
          type: integer
          format: int32
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 0
          type: integer
          format: int32
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/resource'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
        - vens
      summary: create resource
      operationId: createResource
      description: Create a new resource.
      security:
        - oAuth2ClientCredentials: [write_vens]
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resource'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if resource with  same resourceIdentifier already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /vens/{venID}/resources/{resourceID}:
    parameters:
      - name: venID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        description: object ID of the associated ven.
        required: true
      - name: resourceID
        in: path
        schema:
          $ref: '#/components/schemas/objectID'
        description: object ID of the resource.
        required: true
    get:
      tags:
        - vens
      summary: search ven resources by ID
      operationId: searchVenResourceByID
      description: Return the ven resource specified by venID and resourceID specified in path.
      security:
        - oAuth2ClientCredentials: [read_all]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    put:
      tags:
        - vens
      summary: update  ven resource
      operationId: updateVenResource
      description: Update the ven resource specified by venID and resourceID specified in path.
      security:
        - oAuth2ClientCredentials: [write_vens]
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resource'
        description: resource item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    delete:
      tags:
        - vens
      summary: delete  ven resource
      operationId: deleteVenResource
      description: Delete the ven resource specified by venID and resourceID specified in path.
      security:
        - oAuth2ClientCredentials: [write_vens]
        - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
  /auth/token:
    post:
      tags:
        - Auth
      summary: fetch a token
      operationId: fetchToken
      description: Return an access token based on clientID and clientSecret.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/clientCredentialRequest'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clientCredentialResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authError'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
components:
  schemas:
    # examples are provided at the element level to aid readability and to support Reference Implementation UI
    program:
      type: object
      description: Provides program specific metadata from VTN to VEN.
      required:
        - programName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
          # VTN provisioned on object creation.
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object creation.
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object modification.
        objectType:
          type: string
          description: Used as discriminator
          enum: [PROGRAM]
          # VTN provisioned on object creation.
        programName:
          type: string
          description: Short name to uniquely identify program.
          minLength: 1
          maxLength: 128
          example: ResTOU
        programLongName:
          type: string
          description: Long name of program for human readability.
          example: Residential Time of Use-A
          nullable: true
          default: null
        retailerName:
          type: string
          description: Short name of energy retailer providing the program.
          example: ACME
          nullable: true
          default: null
        retailerLongName:
          type: string
          description: Long name of energy retailer for human readability.
          example: ACME Electric Inc.
          nullable: true
          default: null
        programType:
          type: string
          description: A program defined categorization.
          example: PRICING_TARIFF
          nullable: true
          default: null
        country:
          type: string
          description: Alpha-2 code per ISO 3166-1.
          example: US
          nullable: true
          default: null
        principalSubdivision:
          type: string
          description: Coding per ISO 3166-2. E.g. state in US.
          example: CO
          nullable: true
          default: null
        timeZoneOffset:
          $ref: '#/components/schemas/duration'
          # Number of hours different from UTC for the standard time applicable to the program.
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod'
          # The temporal span of the program, could be years long.
        programDescriptions:
          type: array
          description: A list of programDescriptions
          items:
            required:
              - URL
            properties:
              URL:
                type: string
                format: uri
                description: A human or machine readable program description
                example: www.myCorporation.com/myProgramDescription
          nullable: true
          default: null
        bindingEvents:
          type: boolean
          description: True if events are fixed once transmitted.
          example: false
          nullable: true
          default: null
        localPrice:
          type: boolean
          description: True if events have been adapted from a grid event.
          example: false
          nullable: true
          default: null
        payloadDescriptors:
          type: array
          description: A list of payloadDescriptors.
          items:
            anyOf:
              - $ref: '#/components/schemas/eventPayloadDescriptor'
              - $ref: '#/components/schemas/reportPayloadDescriptor'
            discriminator:
              propertyName: objectType
          nullable: true
          default: null
        targets:
          type: array
          description: A list of valuesMap objects.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
    report:
      type: object
      description: report object.
      required:
        - programID
        - eventID
        - clientName
        - resources
      properties:
        id:
          $ref: '#/components/schemas/objectID'
          # VTN provisioned on object creation.
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object creation.
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object modification.
        objectType:
          type: string
          description: Used as discriminator
          enum: [REPORT]
          # VTN provisioned on object creation.
        programID:
          $ref: '#/components/schemas/objectID'
          # ID attribute of program object this report is associated with.
        eventID:
          $ref: '#/components/schemas/objectID'
          # ID attribute of event object this report is associated with.
        clientName:
          type: string
          description: User generated identifier; may be VEN ID provisioned out-of-band.
          minLength: 1
          maxLength: 128
          example: VEN-999
        reportName:
          type: string
          description: User defined string for use in debugging or User Interface.
          example: Battery_usage_04112023
          nullable: true
          default: null
        payloadDescriptors:
          type: array
          description: A list of reportPayloadDescriptors.
          items:
            $ref: '#/components/schemas/reportPayloadDescriptor'
          nullable: true
          default: null
          # An optional list of objects that provide context to payload types.
        resources:
          type: array
          description: A list of objects containing report data for a set of resources.
          items:
            type: object
            description: Report data associated with a resource.
            required:
              - resourceName
              - intervals
            properties:
              resourceName:
                type: string
                minLength: 1
                maxLength: 128
                description: User generated identifier. A value of AGGREGATED_REPORT indicates an aggregation of more that one resource's data
                example: RESOURCE-999
              intervalPeriod:
                $ref: '#/components/schemas/intervalPeriod'
                # Defines default start and durations of intervals.
              intervals:
                type: array
                description: A list of interval objects.
                items:
                  $ref: '#/components/schemas/interval'
    event:
      type: object
      description: |
        Event object to communicate a Demand Response request to VEN.
        If intervalPeriod is present, sets default start time and duration of intervals.
      required:
        - programID
        - intervals
      properties:
        id:
          $ref: '#/components/schemas/objectID'
          # VTN provisioned on object creation.
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object creation.
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object modification.
        objectType:
          type: string
          description: Used as discriminator
          enum: [EVENT]
          # VTN provisioned on object creation.
        programID:
          $ref: '#/components/schemas/objectID'
          # ID attribute of program object this event is associated with.
        eventName:
          type: string
          description: User defined string for use in debugging or User Interface.
          example: price event 11-18-2022
          nullable: true
          default: null
        priority:
          type: integer
          minimum: 0
          description: Relative priority of event. A lower number is a higher priority.
          example: 0
          nullable: true
          default: null
        targets:
          type: array
          description: A list of valuesMap objects.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
        reportDescriptors:
          type: array
          description: A list of reportDescriptor objects. Used to request reports from VEN.
          items:
            $ref: '#/components/schemas/reportDescriptor'
          nullable: true
          default: null
        payloadDescriptors:
          type: array
          description: A list of payloadDescriptor objects.
          items:
            $ref: '#/components/schemas/eventPayloadDescriptor'
          nullable: true
          default: null
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod'
          # Defines default start and durations of intervals.
        intervals:
          type: array
          description: A list of interval objects.
          items:
            $ref: '#/components/schemas/interval'
    subscription:
      type: object
      description: |
        An object created by a client to receive notification of operations on objects.
        Clients may subscribe to be notified when a type of object is created,
        updated, or deleted.
      required:
        - clientName
        - programID
        - objectOperations
      properties:
        id:
          $ref: '#/components/schemas/objectID'
          # VTN provisioned on object creation.
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object creation.
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object modification.
        objectType:
          type: string
          description: Used as discriminator.
          enum: [SUBSCRIPTION]
          # VTN provisioned on object creation.
        clientName:
          type: string
          description: User generated identifier, may be VEN identifier provisioned out-of-band.
          minLength: 1
          maxLength: 128
          example: VEN-999
        programID:
          $ref: '#/components/schemas/objectID'
          # ID attribute of program object this subscription is associated with.
        objectOperations:
          type: array
          description: list of objects and operations to subscribe to.
          items:
            type: object
            description: object type, operations, and callbackUrl.
            required:
              - objects
              - operations
              - callbackUrl
            properties:
              objects:
                type: array
                description: list of objects to subscribe to.
                items:
                  $ref: '#/components/schemas/objectTypes'
              operations:
                type: array
                description: list of operations to subscribe to.
                items:
                  type: string
                  description: object operation to subscribe to.
                  example: POST
                  enum: [GET, POST, PUT, DELETE]
              callbackUrl:
                type: string
                format: uri
                description: User provided webhook URL.
                example: https://myserver.com/send/callback/here
              bearerToken:
                type: string
                description: |
                  User provided token.
                  To avoid custom integrations, callback endpoints
                  should accept the provided bearer token to authenticate VTN requests.
                example: NCEJGI9E8ER9802UT9HUG
                nullable: true
                default: null
        targets:
          type: array
          description: A list of valuesMap objects. Used by server to filter callbacks.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
    ven:
      type: object
      description: Ven represents a client with the ven role.
      required:
        - venName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
          # VTN provisioned on object creation.
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object creation.
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object modification.
        objectType:
          type: string
          description: Used as discriminator.
          enum: [VEN]
          # VTN provisioned on object creation.
        venName:
          type: string
          description: |
            User generated identifier, may be VEN identifier provisioned out-of-band.
            venName is expected to be unique within the scope of a VTN
          minLength: 1
          maxLength: 128
          example: VEN-999
        attributes:
          type: array
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
        targets:
          type: array
          description: A list of valuesMap objects describing target criteria.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
        resources:
          type: array
          description: A list of resource objects representing end-devices or systems.
          items:
            $ref: '#/components/schemas/resource'
          nullable: true
          default: null
    resource:
      type: object
      description: |
        A resource is an energy device or system subject to control by a VEN.
      required:
        - resourceName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
          # VTN provisioned on object creation.
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object creation.
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
          #  VTN provisioned on object modification.
        objectType:
          type: string
          description: Used as discriminator.
          enum: [RESOURCE]
          # VTN provisioned on object creation.
        resourceName:
          type: string
          description: |
            User generated identifier, resource may be configured with identifier out-of-band.
            resourceName is expected to be unique within the scope of the associated VEN.
          minLength: 1
          maxLength: 128
          example: RESOURCE-999
        venID:
          $ref: '#/components/schemas/objectID'
          # VTN provisioned on object creation based on path, e.g. POST <>/ven/{venID}/resources.
        attributes:
          type: array
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
        targets:
          type: array
          description: A list of valuesMap objects describing target criteria.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
    interval:
      type: object
      description: |
        An object defining a temporal window and a list of valuesMaps.
        if intervalPeriod present may set temporal aspects of interval or override event.intervalPeriod.
      required:
        - id
        - payloads
      properties:
        id:
          type: integer
          format: int32
          description: A client generated number assigned an interval object. Not a sequence number.
          example: 0
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod'
          # Defines start and duration of interval.
        payloads:
          type: array
          description: A list of valuesMap objects.
          items:
            $ref: '#/components/schemas/valuesMap'
    intervalPeriod:
      type: object
      description: |
        Defines temporal aspects of intervals.
        A duration of default PT0S indicates instantaneous or infinity, depending on payloadType.
        A randomizeStart of default null indicates no randomization.
      required:
        - start
      properties:
        start:
          $ref: '#/components/schemas/dateTime'
          #  The start time of an interval or set of intervals.
        duration:
          $ref: '#/components/schemas/duration'
          #  The duration of an interval or set of intervals.
        randomizeStart:
          $ref: '#/components/schemas/duration'
          #  Indicates a randomization time that may be applied to start.
    valuesMap:
      type: object
      description: |
        Represents one or more values associated with a type.
        E.g. a type of PRICE contains a single float value.
      required:
        - type
        - values
      properties:
        type:
          type: string
          minLength: 1
          maxLength: 128
          description: |
            Enumerated or private string signifying the nature of values.
            E.G. "PRICE" indicates value is to be interpreted as a currency.
          example: PRICE
        values:
            type: array
            description: A list of data points. Most often a singular value such as a price.
            example: [0.17]
            items:
              anyOf:
                - type: number
                - type: integer
                - type: string
                - type: boolean
                - $ref: '#/components/schemas/point'
    point:
      type: object
      description: A pair of floats typically used as a point on a 2 dimensional grid.
      required:
        - x
        - y
      properties:
        x:
          type: number
          format: float
          description: A value on an x axis.
          example: 1.0
        y:
          type: number
          format: float
          description: A value on a y axis.
          example: 2.0
    eventPayloadDescriptor:
      type: object
      description: |
        Contextual information used to interpret event valuesMap values.
        E.g. a PRICE payload simply contains a price value, an
        associated descriptor provides necessary context such as units and currency.
      required:
        - payloadType
      properties:
        objectType:
          type: string
          description: Used as discriminator.
          enum: [EVENT_PAYLOAD_DESCRIPTOR]
        payloadType:
          type: string
          description: Enumerated or private string signifying the nature of values.
          minLength: 1
          maxLength: 128
          example: PRICE
        units:
          type: string
          description: Units of measure.
          example: KWH
          nullable: true
          default: null
        currency:
          type: string
          description: Currency of price payload.
          example: USD
          nullable: true
          default: null
    reportPayloadDescriptor:
      type: object
      description: |
        Contextual information used to interpret report payload values.
        E.g. a USAGE payload simply contains a usage value, an
        associated descriptor provides necessary context such as units and data quality.
      required:
        - payloadType
      properties:
        objectType:
          type: string
          description: Used as discriminator.
          enum: [REPORT_PAYLOAD_DESCRIPTOR]
        payloadType:
          type: string
          description: Enumerated or private string signifying the nature of values.
          minLength: 1
          maxLength: 128
          example: USAGE
        readingType:
          type: string
          description: Enumerated or private string signifying the type of reading.
          example: DIRECT_READ
          nullable: true
          default: null
        units:
          type: string
          description: Units of measure.
          example: KWH
          nullable: true
          default: null
        accuracy:
          type: number
          format: float
          description: A quantification of the accuracy of a set of payload values.
          example: 0.0
          nullable: true
          default: null
        confidence:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          description: A quantification of the confidence in a set of payload values.
          example: 100
          nullable: true
          default: null
    reportDescriptor:
      type: object
      description: |
        An object that may be used to request a report from a VEN.
      required:
        - payloadType
      properties:
        payloadType:
          type: string
          description: Enumerated or private string signifying the nature of values.
          minLength: 1
          maxLength: 128
          example: USAGE
        readingType:
          type: string
          description: Enumerated or private string signifying the type of reading.
          example: DIRECT_READ
          nullable: true
          default: null
        units:
          type: string
          description: Units of measure.
          example: KWH
          nullable: true
          default: null
        targets:
          type: array
          description: A list of valuesMap objects.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
        aggregate:
          type: boolean
          description: |
            True if report should aggregate results from all targeted resources.
            False if report includes results for each resource.
          example: false
          default: false
        startInterval:
          type: integer
          format: int32
          description: |
            The interval on which to generate a report.
            -1 indicates generate report at end of last interval.
          example: -1
          default: -1
        numIntervals:
          type: integer
          format: int32
          description: |
            The number of intervals to include in a report.
            -1 indicates that all intervals are to be included.
          example: -1
          default: -1
        historical:
          type: boolean
          description: |
            True indicates report on intervals preceding startInterval.
            False indicates report on intervals following startInterval (e.g. forecast).
          example: true
          default: true
        frequency:
          type: integer
          format: int32
          description: |
            Number of intervals that elapse between reports.
            -1 indicates same as numIntervals.
          example: -1
          default: -1
        repeat:
          type: integer
          format: int32
          description: |
            Number of times to repeat report.
            1 indicates generate one report.
            -1 indicates repeat indefinitely.
          example: 1
          default: 1
    objectID:
        type: string
        pattern: "^[a-zA-Z0-9_-]*$"
        minLength: 1
        maxLength: 128
        description: URL safe VTN assigned object ID.
        example: object-999
    notification:
      type: object
      description: |
        VTN generated object included in request to subscription callbackUrl.
      required:
        - objectType
        - operation
        - object
      properties:
        objectType:
          $ref: '#/components/schemas/objectTypes'
        operation:
          type: string
          description: the operation on on object that triggered the notification.
          example: POST
          enum: [GET, POST, PUT, DELETE]
        object:
          type: object
          description: the object that is the subject of the notification.
          example: {}
          oneOf:
            - $ref: '#/components/schemas/program'
            - $ref: '#/components/schemas/report'
            - $ref: '#/components/schemas/event'
            - $ref: '#/components/schemas/subscription'
            - $ref: '#/components/schemas/ven'
            - $ref: '#/components/schemas/resource'
          discriminator:
            propertyName: objectType
        targets:
          type: array
          description: A list of valuesMap objects.
          items:
            $ref: '#/components/schemas/valuesMap'
          nullable: true
          default: null
    objectTypes:
      type: string
      description: Types of objects addressable through API.
      example: EVENT
      enum: [PROGRAM, EVENT, REPORT, SUBSCRIPTION, VEN, RESOURCE]
    dateTime:
      type: string
      format: date-time
      description: datetime in ISO 8601 format
      example: 2023-06-15T09:30:00Z
    duration:
      type: string
      pattern: "^(-?)P(?=\\d|T\\d)(?:(\\d+)Y)?(?:(\\d+)M)?(?:(\\d+)([DW]))?(?:T(?:(\\d+)H)?(?:(\\d+)M)?(?:(\\d+(?:\\.\\d+)?)S)?)?$"
      description: duration in ISO 8601 format
      example: PT1H
      default: PT0S
    clientCredentialRequest:
      type: object
      description: |
        Body of POST request to /auth/token. Note snake case per https://www.rfc-editor.org/rfc/rfc6749
      required:
        - grant_type
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          description: OAuth2 grant type, must be 'client_credentials'
          example: client_credentials
          enum: [client_credentials]
        client_id:
          type: string
          minLength: 1
          maxLength: 4096
          description: client ID to exchange for bearer token.
          example: ven_client_99
        client_secret:
          type: string
          minLength: 1
          maxLength: 4096
          description: client secret to exchange for bearer token.
          example: ven_secret_99
        scope:
          type: string
          minLength: 0
          maxLength: 4096
          description: application defined scope.
          example: read_all
    clientCredentialResponse:
      type: object
      description: |
        Body response from /auth/token. Note snake case per https://www.rfc-editor.org/rfc/rfc6749
      required:
        - access_token
        - token_type
      properties:
        access_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: access token povided by Authorization service
          example: MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3
        token_type:
          type: string
          description: token type, must be Bearer.
          example: Bearer
          enum: [Bearer]
        expires_in:
          type: integer
          description: expiration period in seconds.
          example: 3600
        refresh_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: refresh token povided by Authorization service
          example: IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk
        scope:
          type: string
          minLength: 0
          maxLength: 4096
          description: application defined scope.
          example: read_all
    authError:
      type: object
      description: error reponse on HTTP 400 from auth/token per https://www.rfc-editor.org/rfc/rfc6749
      required:
        - error
      properties:
        error:
          type: string
          description: As described in rfc6749 |
            invalid_request – The request is missing a parameter so the server can’t proceed with the request. This may also be returned if the request includes an unsupported parameter or repeats a parameter.
            invalid_client – Client authentication failed, such as if the request contains an invalid client ID or secret. Send an HTTP 401 response in this case.
            invalid_grant – The authorization code (or user’s password for the password grant type) is invalid or expired. This is also the error you would return if the redirect URL given in the authorization grant does not match the URL provided in this access token request.
            invalid_scope – For access token requests that include a scope (password or client_credentials grants), this error indicates an invalid scope value in the request.
            unauthorized_client – This client is not authorized to use the requested grant type. For example, if you restrict which applications can use the Implicit grant, you would return this error for the other apps.
            unsupported_grant_type – If a grant type is requested that the authorization server doesn’t recognize, use this code. Note that unknown grant types also use this specific error code rather than using the invalid_request above.
          example: invalid_request
          enum: [invalid_request, invalid_client, invalid_grant, invalid_scope, unauthorized_client, unsupported_grant_type]
        error_description:
          type: string
          description: Should be a sentence or two at most describing the circumstance of the error
          example: Request was missing the 'client_id' parameter.
        error_uri:
          type: string
          format: uri
          description: Optional reference to more detailed error description
          example: See the full API docs at https://authorization-server.com/docs/access_toke
    problem:
      type: object
      description: |
        reusable error response. From https://opensource.zalando.com/problem/schema.yaml.
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type.
            When dereferenced, it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: 'about:blank'
          example: 'https://zalando.github.io/problem/constraint-violation'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in english and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable.
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: Client credential flow.
      # x-tokenInfoFunc: auth.verifyToken
      flows:
        clientCredentials:
          tokenUrl: auth/token
          scopes:
            read_all: VENs and BL can read all resources
            write_programs: Only BL can write to programs
            write_events: Only BL can write to events
            write_reports: only VENs can write to reports
            write_subscriptions: VENs and BL can write to subscriptions
            write_vens: VENS and BL can write to vens and resources
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes