OpenADR Alliance Programs API

openapi: 3.2.0
info:
  title: Openadr Alliance Programs API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
  description: 'Operations tagged programs across 4 of this provider''s published API definitions: openadr-3-0-0-openapi.yaml, openadr-3-0-1-openapi.yaml, openadr-3-1-0-openapi.yaml, openadr-3-1-1-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- description: base path
  url: http://localhost:8081/openadr3
- description: base path
  url: http://localhost:8081/openadr3/3.0.1
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
tags:
- name: programs
paths:
  /programs:
    get:
      tags:
      - programs
      summary: searches all programs
      operationId: searchAllPrograms
      description: 'List all programs known to the server.

        Use skip and pagination query params to limit response size.

        '
      security:
      - oAuth2ClientCredentials:
        - read_all
      - 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'
    servers:
    - description: base path
      url: http://localhost:8081/openadr3
  /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'
        '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'
        '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'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    servers:
    - description: base path
      url: http://localhost:8081/openadr3
components:
  schemas:
    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
          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'
    dateTime:
      type:
      - string
      - 'null'
      description: datetime in ISO 8601 format
      example: 2023-06-15 09:30:00+00:00
      default: null
    intervalPeriod:
      type: object
      description: 'Defines temporal aspects of intervals.

        A duration of default null indicates infinity.

        A randomizeStart of default null indicates no randomization.

        '
      required:
      - start
      properties:
        start:
          $ref: '#/components/schemas/dateTime'
        duration:
          $ref: '#/components/schemas/duration'
        randomizeStart:
          $ref: '#/components/schemas/duration'
    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
          example: 503
          exclusiveMaximum: 600
        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.

            '
    duration:
      type:
      - string
      - 'null'
      description: duration in ISO 8601 format
      example: PT1H
      default: null
    objectID:
      type: string
      pattern: ^[a-zA-Z0-9_-]*$
      minLength: 1
      maxLength: 128
      description: URL safe VTN assigned object ID.
      example: object-999
    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, e.g. program.payloadDescriptors
          default: REPORT_PAYLOAD_DESCRIPTOR
        payloadType:
          type: string
          description: Enumerated or private string signifying the nature of values.
          example: USAGE
        readingType:
          type: string
          description: Enumerated or private string signifying the type of reading.
          example: DIRECT_READ
          default: DIRECT_READ
        units:
          type: string
          description: Units of measure.
          example: KWH
          default: KWH
        accuracy:
          type: number
          format: float
          description: A quantification of the accuracy of a set of payload values.
          example: 0.0
          default: 0.0
        confidence:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          description: A quantification of the confidence in a set of payload values.
          example: 100
          default: 100
    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, e.g. program.payloadDescriptors
          default: EVENT_PAYLOAD_DESCRIPTOR
        payloadType:
          type: string
          description: Enumerated or private string signifying the nature of values.
          example: PRICE
        units:
          type: string
          description: Units of measure.
          example: KWH
          default: KWH
        currency:
          type: string
          description: Currency of price payload.
          example: USD
          default: USD
    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
          - 'null'
          format: float
          description: A value on an x axis.
          example: 1.0
          default: null
        y:
          type:
          - number
          - 'null'
          format: float
          description: A value on a y axis.
          example: 2.0
          default: null
    program:
      type: object
      description: Provides program specific metadata from VTN to VEN.
      required:
      - programName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          type: string
          description: Used as discriminator, e.g. notification.object
          enum:
          - PROGRAM
        programName:
          type: string
          description: Short name to uniquely identify program.
          example: ResTOU
        programLongName:
          type:
          - string
          - 'null'
          description: Long name of program for human readability.
          example: Residential Time of Use-A
          default: null
        retailerName:
          type:
          - string
          - 'null'
          description: Short name of energy retailer providing the program.
          example: ACME
          default: null
        retailerLongName:
          type:
          - string
          - 'null'
          description: Long name of energy retailer for human readability.
          example: ACME Electric Inc.
          default: null
        programType:
          type:
          - string
          - 'null'
          description: A program defined categorization.
          example: PRICING_TARIFF
          default: null
        country:
          type:
          - string
          - 'null'
          description: Alpha-2 code per ISO 3166-1.
          example: US
          default: null
        principalSubdivision:
          type:
          - string
          - 'null'
          description: Coding per ISO 3166-2. E.g. state in US.
          example: CO
          default: null
        timeZoneOffset:
          $ref: '#/components/schemas/duration'
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod'
        programDescriptions:
          type:
          - array
          - 'null'
          description: A list of programDescriptions
          default: null
          items:
            required:
            - URL
            properties:
              URL:
                type: string
                format: uri
                description: A human or machine readable program description
                example: www.myCorporation.com/myProgramDescription
        bindingEvents:
          type: boolean
          description: True if events are fixed once transmitted.
          example: false
          default: false
        localPrice:
          type: boolean
          description: True if events have been adapted from a grid event.
          example: false
          default: false
        payloadDescriptors:
          type:
          - array
          - 'null'
          description: A list of payloadDescriptors.
          default: null
          items:
            anyOf:
            - $ref: '#/components/schemas/eventPayloadDescriptor'
            - $ref: '#/components/schemas/reportPayloadDescriptor'
            discriminator:
              propertyName: objectType
        targets:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects.
          default: null
          items:
            $ref: '#/components/schemas/valuesMap'
    valuesMap_2:
      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_2'
    dateTime_2:
      type: string
      format: date-time
      description: datetime in ISO 8601 format
      example: 2023-06-15 09:30:00+00:00
    intervalPeriod_2:
      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_2'
        duration:
          $ref: '#/components/schemas/duration_2'
        randomizeStart:
          $ref: '#/components/schemas/duration_2'
    duration_2:
      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
    reportPayloadDescriptor_2:
      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
          - 'null'
          description: Enumerated or private string signifying the type of reading.
          example: DIRECT_READ
          default: null
        units:
          type:
          - string
          - 'null'
          description: Units of measure.
          example: KWH
          default: null
        accuracy:
          type:
          - number
          - 'null'
          format: float
          description: A quantification of the accuracy of a set of payload values.
          example: 0.0
          default: null
        confidence:
          type:
          - integer
          - 'null'
          format: int32
          minimum: 0
          maximum: 100
          description: A quantification of the confidence in a set of payload values.
          example: 100
          default: null
    eventPayloadDescriptor_2:
      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
          - 'null'
          description: Units of measure.
          example: KWH
          default: null
        currency:
          type:
          - string
          - 'null'
          description: Currency of price payload.
          example: USD
          default: null
    point_2:
      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
    program_2:
      type: object
      description: Provides program specific metadata from VTN to VEN.
      required:
      - programName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime_2'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime_2'
        objectType:
          type: string
          description: Used as discriminator
          enum:
          - PROGRAM
        programName:
          type: string
          description: Short name to uniquely identify program.
          minLength: 1
          maxLength: 128
          example: ResTOU
        programLongName:
          type:
          - string
          - 'null'
          description: Long name of program for human readability.
          example: Residential Time of Use-A
          default: null
        retailerName:
          type:
          - string
          - 'null'
          description: Short name of energy retailer providing the program.
          example: ACME
          default: null
        retailerLongName:
          type:
          - string
          - 'null'
          description: Long name of energy retailer for human readability.
          example: ACME Electric Inc.
          default: null
        programType:
          type:
          - string
          - 'null'
          description: A program defined categorization.
          example: PRICING_TARIFF
          default: null
        country:
          type:
          - string
          - 'null'
          description: Alpha-2 code per ISO 3166-1.
          example: US
          default: null
        principalSubdivision:
          type:
          - string
          - 'null'
          description: Coding per ISO 3166-2. E.g. state in US.
          example: CO
          default: null
        timeZoneOffset:
          $ref: '#/components/schemas/duration_2'
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod_2'
        programDescriptions:
          type:
          - array
          - 'null'
          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
          default: null
        bindingEvents:
          type:
          - boolean
          - 'null'
          description: True if events are fixed once transmitted.
          example: false
          default: null
        localPrice:
          type:
          - boolean
          - 'null'
          description: True if events have been adapted from a grid event.
          example: false
          default: null
        payloadDescriptors:
          type:
          - array
          - 'null'
          description: A list of payloadDescriptors.
          items:
            anyOf:
            - $ref: '#/components/schemas/eventPayloadDescriptor_2'
            - $ref: '#/components/schemas/reportPayloadDescriptor_2'
            discriminator:
              propertyName: objectType
          default: null
        targets:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects.
          items:
            $ref: '#/components/schemas/valuesMap_2'
          default: null
    valuesMap_3:
      type: object
      description: 'Represents one or more values associated with a type.


        See enumerations in Definitions for defined string values, or use privately defined strings

        '
      required:
      - type
      - values
      properties:
        type:
          type: string
          minLength: 1
          maxLength: 128
          description: 'Represents the nature of values.


            See enumerations in Definitions for defined string values, or use privately defined strings

            '
          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_3'
    target:
      type: string
      minLength: 1
      maxLength: 128
      description: User generated target string.
      example: group-1
    readingType:
      type:
      - string
      - 'null'
      description: 'Represents the type of reading.


        See enumerations in Definitions for defined string values, or use privately defined strings

        '
      example: DIRECT_READ
      minLength: 1
      maxLength: 128
      default: null
    objectTypes:
      type: string
      description: Types of objects addressable through API.
      example: EVENT
      enum:
      - PROGRAM
      - EVENT
      - REPORT
      - SUBSCRIPTION
      - VEN
      - RESOURCE
    objectMetadata:
      type: object
      description: metadata common to all addressable objects. Values provided by VTN on object creation.
      required:
      - id
      - createdDateTime
      - modificationDateTime
      - objectType
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime_3'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime_3'
        objectType:
          $ref: '#/components/schemas/objectTypes'
    duration_3:
      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
    units:
      type:
      - string
      - 'null'
      description: Units of measure.
      example: KWH
      default: null
      minLength: 1
      maxLength: 128
    point_3:
      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
    programRequest:
      type: object
      description: Client provided description of program
      required:
      - programName
      properties:
        programName:
          type: string
          description: Short name to uniquely identify program.
          minLength: 1
          maxLength: 128
          example: ResTOU
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod_3'
        programDescriptions:
          type:
          - array
          - 'null'
          description: A list of programDescriptions
          items:
            required:
            - URL
            properties:
              URL:
                type: string
                format: uri
                minLength: 2
                maxLength: 8000
                description: A human or machine readable program description
                example: https://www.myCorporation.com/myProgramDescription
          default: null
        payloadDescriptors:
          type:
          - array
          - 'null'
          description: A list of payloadDescriptors.
          items:
            anyOf:
            - $ref: '#/components/schemas/eventPayloadDescriptor_3'
            - $ref: '#/components/schemas/reportPayloadDescriptor_3'
            discriminator:
              propertyName: objectType
          default: null
        attributes:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap_3'
          default: null
        targets:
          type:
          - array
          - 'null'
          description: A list of targets.
          items:
            $ref: '#/components/schemas/target'
          default: null
    dateTime_3:
      type: string
      format: date-time
      description: datetime in RFC 3339 format
      example: 2023-06-15 09:30:00+00:00
    intervalPeriod_3:
      type: object
      description: 'Defines temporal aspects of intervals.

        A start of "0001-01-01" or "0001-01-01T00:00:00" may indicate ''now''. See User Guide.

        A duration of "P9999Y" may indicate infinity. See User Guide.

        A randomizeStart indicates absolute range of client applied offset to start. See User Guide.

        '
      properties:
        start:
          $ref: '#/components/schemas/dateTime_3'
        duration:
          $ref: '#/components/schemas/duration_3'
        randomizeStart:
          $ref: '#/components/schemas/duration_3'
    reportPayloadDescriptor_3:
      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:
      - objectType
      - payloadType
      properties:
        objectType:
          type: string
          description: Used as discriminator.
          enum:
          - REPORT_PAYLOAD_DESCRIPTOR
        payloadType:
          type: string
          description: 'Represents the nature of values.


            See enumerations in Definitions for defined string values, or use privately defined strings

            '
          minLength: 1
          maxLength: 128
          example: USAGE
        readingType:
          $ref: '#/components/schemas/readingType'
        units:
          $ref: '#/components/schemas/units'
        accuracy:
          type:
          - number
          - 'null'
          format: float
          description: A quantification of the accuracy of a set of payload values.
          example: 0.0
          default: null
        confidence:
          type:
          - integer
          - 'null'
          format: int32
          minimum: 0
          maximum: 100
       

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openadr-alliance/refs/heads/main/openapi/openadr-alliance-programs-api-openapi.yml