# generated: 2026-07-27 # method: derived # source: openapi/openadr-3-1-1-openapi.yaml + https://github.com/grid-coordination/openadr3-specification/blob/main/doc/ # NOTE: derived by API Evangelist. The OpenADR Alliance publishes no AsyncAPI document. asyncapi: 3.0.0 info: title: OpenADR 3 Object Operation Notifications version: 3.1.1 description: 'Event surface of the OpenADR 3 protocol, derived from the OpenADR 3.1.1 OpenAPI contract and the Alliance-published notifications design document. The OpenADR Alliance publishes no AsyncAPI document of its own; this one is an API Evangelist derivation and is NOT a normative Alliance artifact. Two notifier bindings exist. WEBHOOK is mandatory for every VTN: a client creates a subscription carrying a callbackUrl, and the VTN POSTs a notification object to it. MQTT was added in 3.1.0 and is optional: the client discovers broker URIs and authentication via GET /notifiers, then discovers VTN-assigned topic names via the GET /notifiers/mqtt/topics/* operations. Topic names are NOT fixed by the specification — they are assigned per client so that a VEN only receives notifications for objects it is authorized to see (object privacy). The channel addresses below therefore use runtime-resolved placeholders rather than invented literal topic strings. ' license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 externalDocs: description: OpenADR3 Object Operation Notifications via Additional Protocols (v1.0.0, 2026-03-15) url: https://github.com/grid-coordination/openadr3-specification/blob/main/doc/OpenADR3%20Object%20Operation%20Notifications%20via%20Additional%20Protocols.md defaultContentType: application/json servers: vtn-webhook: host: implementer-hosted protocol: https description: The VTN that publishes notifications by POSTing to a subscription callbackUrl. Each implementer hosts its own; the Alliance hosts none. vtn-mqtt-broker: host: broker.vtn.example.com protocol: mqtts description: MQTT broker advertised by the VTN in the MQTT notifier binding (mqttNotifierBindingObject.URIS). Discovered at runtime via GET /notifiers; the host shown is the placeholder pattern used in the specification example, not a real broker. security: - $ref: '#/components/securitySchemes/mqttOauth2Bearer' - $ref: '#/components/securitySchemes/mqttCertificate' - $ref: '#/components/securitySchemes/mqttAnonymous' channels: webhookCallback: address: '{callbackUrl}' title: Subscription webhook callback description: The callbackUrl registered on each subscription.objectOperations[] entry. Declared in the OpenAPI as the notifyEvent callback on POST /subscriptions with security [{}]. The subscriber may supply a bearerToken alongside the callbackUrl, which the VTN is expected to present on its requests, but that token is not modelled on the callback operation itself and there is no payload signature or replay defence. servers: - $ref: '#/servers/vtn-webhook' parameters: callbackUrl: description: Absolute URL supplied by the subscriber in subscription.objectOperations[].callbackUrl. messages: objectOperationNotification: $ref: '#/components/messages/objectOperationNotification' mqttObjectTopic: address: '{topic}' title: MQTT object-operation topic description: A VTN-assigned MQTT topic carrying notifications for one object type and one operation (or ALL). Resolve the concrete name from notifierTopicsResponse.topics.{CREATE|UPDATE|DELETE|ALL} returned by the matching GET /notifiers/mqtt/topics/* operation. The specification example pattern is "{objectType}s/create", "{objectType}s/update", "{objectType}s/delete", "{objectType}s/+", but a VTN may name topics however it likes and MAY scope them per VEN. servers: - $ref: '#/servers/vtn-mqtt-broker' parameters: topic: description: Runtime-resolved topic name from the notifier topics endpoints. messages: objectOperationNotification: $ref: '#/components/messages/objectOperationNotification' operations: receiveWebhookNotification: action: receive channel: $ref: '#/channels/webhookCallback' title: Receive a notification on a subscription callback URL description: The VTN POSTs a notification to the subscriber. The subscriber returns 200 to accept it, or a problem document on 400. bindings: http: method: POST messages: - $ref: '#/channels/webhookCallback/messages/objectOperationNotification' receiveMqttNotification: action: receive channel: $ref: '#/channels/mqttObjectTopic' title: Receive a notification from an MQTT notifier topic description: The subscriber consumes JSON-serialized notifications from a VTN-assigned topic. Target-based filtering is not available on this binding; object privacy is enforced by VEN-scoped topics instead. messages: - $ref: '#/channels/mqttObjectTopic/messages/objectOperationNotification' components: messages: objectOperationNotification: name: objectOperationNotification title: Object operation notification summary: VTN generated object included in request to subscription callbackUrl. contentType: application/json payload: $ref: '#/components/schemas/notification' securitySchemes: mqttAnonymous: type: userPassword description: mqttNotifierAuthenticationAnonymous — the VTN broker accepts anonymous connections. mqttOauth2Bearer: type: httpApiKey name: Authorization in: user description: mqttNotifierAuthenticationOauth2BearerToken — the same OAuth 2.0 client-credentials JWT used on the REST surface. mqttCertificate: type: X509 description: mqttNotifierAuthenticationCertificate — client certificate, consistent with the OpenADR Alliance PKI. schemas: 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: UPDATE enum: - CREATE - READ - UPDATE - DELETE object: type: object description: the object that is the subject of the notification. 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 example: id: object-999 objectType: PROGRAM createdDateTime: '2023-06-15T09:30:00Z' modificationDateTime: '2023-06-15T09:30:00Z' programName: ResTOU targets: type: array description: A list of targets. items: $ref: '#/components/schemas/target' nullable: true objectTypes: type: string description: Types of objects addressable through API. example: EVENT enum: - PROGRAM - EVENT - REPORT - SUBSCRIPTION - VEN - RESOURCE program: type: object description: Server provided representation of program allOf: - $ref: '#/components/schemas/objectMetadata' - $ref: '#/components/schemas/programRequest' 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' programDescriptions: type: array 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 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 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 targets. items: $ref: '#/components/schemas/target' nullable: true event: type: object description: Server provided representation of event allOf: - $ref: '#/components/schemas/objectMetadata' - $ref: '#/components/schemas/eventRequest' eventRequest: 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 properties: programID: $ref: '#/components/schemas/objectID' eventName: type: string description: User defined string for use in debugging or User Interface. example: price event 11-18-2022 nullable: true default: null duration: $ref: '#/components/schemas/duration' 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 targets. items: $ref: '#/components/schemas/target' nullable: true 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' intervals: type: array description: A list of interval objects. items: $ref: '#/components/schemas/interval' report: type: object description: Server provided representation of report allOf: - $ref: '#/components/schemas/objectMetadata' - $ref: '#/components/schemas/reportRequest' - type: object required: - clientID properties: clientID: $ref: '#/components/schemas/clientID' reportRequest: type: object description: report object. required: - eventID - clientName - resources properties: eventID: $ref: '#/components/schemas/objectID' clientName: $ref: '#/components/schemas/clientName' 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 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: $ref: '#/components/schemas/resourceName' intervalPeriod: $ref: '#/components/schemas/intervalPeriod' intervals: type: array description: A list of interval objects. items: $ref: '#/components/schemas/interval' subscription: type: object description: Server provided representation of subscription allOf: - $ref: '#/components/schemas/objectMetadata' - $ref: '#/components/schemas/subscriptionRequest' - type: object required: - clientID properties: clientID: $ref: '#/components/schemas/clientID' subscriptionRequest: 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 - objectOperations properties: clientName: $ref: '#/components/schemas/clientName' programID: $ref: '#/components/schemas/objectID' 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: CREATE enum: - READ - CREATE - UPDATE - DELETE callbackUrl: type: string format: uri minLength: 2 maxLength: 8000 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 target objects. Used by server to filter notifications. items: $ref: '#/components/schemas/target' nullable: true ven: type: object description: Server provided representation of ven allOf: - $ref: '#/components/schemas/objectMetadata' - $ref: '#/components/schemas/BlVenRequest' venRequest: oneOf: - $ref: '#/components/schemas/VenVenRequest' - $ref: '#/components/schemas/BlVenRequest' BlVenRequest: type: object description: Business Logic provided representation of ven. required: - objectType - clientID - venName properties: objectType: type: string description: Used as discriminator. enum: - BL_VEN_REQUEST clientID: $ref: '#/components/schemas/clientID' targets: type: array description: A list of targets. items: $ref: '#/components/schemas/target' nullable: true venName: $ref: '#/components/schemas/venName' attributes: type: array description: A list of valuesMap objects describing attributes. items: $ref: '#/components/schemas/valuesMap' nullable: true default: null VenVenRequest: type: object description: VEN provided representation of ven. required: - objectType - venName properties: objectType: type: string description: Used as discriminator. enum: - VEN_VEN_REQUEST venName: $ref: '#/components/schemas/venName' attributes: type: array description: A list of valuesMap objects describing attributes. items: $ref: '#/components/schemas/valuesMap' nullable: true default: null resource: type: object description: Server provided representation of resource allOf: - $ref: '#/components/schemas/objectMetadata' - $ref: '#/components/schemas/BlResourceRequest' resourceRequest: oneOf: - $ref: '#/components/schemas/BlResourceRequest' - $ref: '#/components/schemas/VenResourceRequest' BlResourceRequest: type: object description: 'Business Logic provided representation of ven resource. ' required: - objectType - resourceName - venID properties: objectType: type: string description: Used as discriminator. enum: - BL_RESOURCE_REQUEST targets: type: array description: A list of targets. items: $ref: '#/components/schemas/target' nullable: true resourceName: $ref: '#/components/schemas/resourceName' venID: $ref: '#/components/schemas/objectID' attributes: type: array description: A list of valuesMap objects describing attributes. items: $ref: '#/components/schemas/valuesMap' nullable: true default: null VenResourceRequest: type: object description: 'Business Logic provided representation of ven resource. ' required: - objectType - resourceName properties: objectType: type: string description: Used as discriminator. enum: - VEN_RESOURCE_REQUEST resourceName: $ref: '#/components/schemas/resourceName' attributes: type: array description: A list of valuesMap objects describing attributes. items: $ref: '#/components/schemas/valuesMap' nullable: true default: null 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' modificationDateTime: $ref: '#/components/schemas/dateTime' objectType: $ref: '#/components/schemas/objectTypes' 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' payloads: type: array description: A list of valuesMap objects. items: $ref: '#/components/schemas/valuesMap' intervalPeriod: 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' duration: $ref: '#/components/schemas/duration' randomizeStart: $ref: '#/components/schemas/duration' valuesMap: 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' 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: - objectType - payloadType properties: objectType: type: string description: Used as discriminator. enum: - EVENT_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: PRICE units: $ref: '#/components/schemas/units' 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: - 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 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: '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' targets: type: array description: A list of targets. items: $ref: '#/components/schemas/target' nullable: true 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 reportIntervals: type: string description: Indicates VEN report interval options. See User Guide. example: INTERVALS enum: - INTERVALS - SUB_INTERVALS - OPEN_INTERVALS default: INTERVALS objectID: type: string pattern: ^[a-zA-Z0-9_-]*$ minLength: 1 maxLength: 128 description: URL safe VTN assigned object ID. example: object-999 clientID: type: string description: 'ClientID as provisioned by Auhtentication Service and associated with client''s bearer token ' minLength: 1 maxLength: 128 example: 249rj49jiej 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 clientName: type: string description: User generated identifier, may be VEN identifier provisioned out-of-band. minLength: 1 maxLength: 128 example: VEN-999 target: type: string minLength: 1 maxLength: 128 description: User generated target string. example: group-1 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 units: type: string description: Units of measure. example: KWH nullable: true default: null minLength: 1 maxLength: 128 readingType: type: string 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 nullable: true default: null dateTime: type: string format: date-time description: datetime in RFC 3339 format example: 2023-06-15 09:30:00+00:00 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