Green Button Documents Library

The following documents provide background on the Green Button initiative as well as providing Important reference documents for Green Button Implementers

Videos || Presentations || Technical || Certification || ESPI Development

Key References

The references in this section represent the principle technical documents that define and describe the Green Button technology. They begin with the base standard for Green Button. Published in 2011, this standard has been updated in January 2020. Corrections and enhancements to the standard have been developed under the auspices of the GBA OpenADE Task Force. See the Community for details on their meetings and process.

NAESB REQ.21 - Energy Services Provider Interface (ESPI) (Web Page)
The base standard on which Green Button technology is built. This web site has introductory information and includes how to purchase the standard. Published January 2020
Green Button Energy Usage Data Exchange Schema (XML XSD) (Document)
The current working XML schema definition that represents the ESPI Resources used in Green Button data representation. This schema can be used to validate any Green Button data set. Note that in the schema most elements are optional. In the implementation agreements used for certification, corresponding elements become mandatory.
Green Button Personal Identifiable Information Data Exchange Schema (XML XSD) (Document)
The current working XML schema definition that represents the PII Resources used in Green Button data representation. This schema can be used to validate any Green Button data set. Note that in the schema most elements are optional. In the implementation agreements used for certification, corresponding elements become mandatory.
OpenADE Task Force Issues List (Document)
This document contains the issues and their resolution that have been addressed since the publishing of the NAESB standard in October, 2011. Additionally, the implementation agreement document contains detailed elaboration of a subset of issues revolving around Green Button Connect My Data.
GreenButton Implementation Agreement (Document)
Details of interoperability implementation agreements for those deploying Connect My Data. Key specifications included in this document are API definition, OAuth 2.0 protocol, and Cyber-security and privacy requirements.

Testing & Certification Library

Testing and Certification of implementations of Green Button Download My Data and Connect My Data are administered by the Green Button Alliance. The references in this section are the basis of the testing and certification program. The Test Steps Spreadsheet contains the ‘source code’ of the testing program. The Test Plan and Test Data Sheet are generated from the spreadsheet programmaticaly.

Green Button DMD Test Plan (Document)
The test plan document describing all the details of Download My Data Testing and Certification
Green Button DownloadMyDataTest Data Sheet (Document)
Derived from the Test Plan, this contains the actual certification test steps
Green Button Certification Function Blocks (Document)
Detail of the features and facilities of Green Button categorized by Function Block containers
Green Button Connect My Data Certification Test Steps Spreadsheet (Document)
The detailed specification of CMD test steps that will be used in CMD Certification

Technical Development Library

OAuth2 Access Tokens Used in CMD (Web Page)
Definition of the access tokens used for the various CMD APIs
The ApplicationInformation Resource (Web Page)
The details of the ESPI ApplicationInformation Resource. This resource describes the relationship between a DataCustodian and it's registered ThirdParty service providers
The Authorization Scope (Web Page)
The scope string used during the OAuth2 authorization process is detailed here in BNF form. The scope string allows for determination of the services provided, duration of the authorization, and many additional details of the data exchanged authorized by the retail customer
Building UUIDs (Web Page)
Green Button resources each have globally unique identifiers, or UUIDs. This document provides guidance on how to create these UUIDs.
Green Button Atom Links (Document)
Best Practices for ESPI resource URL design
Green Button Connect My Data API Spreadsheet (Document)
A summary of the REST APIs available in Green Button Connect My Data
Green Button SDK Users Guide (Web Page)
The Users guide to the SDK Took Kit - for analyzing and creating Green Button Data Files
Green Button On-Line Validator (Web Page)
A web accessible tool to allow you to validate Green Button data files you may have received from your Utility.

OpenESPI Development

OpenESPI Development Environment (Web Page)
Notes on how to set up an OpenESPI development environment.
GitHub and Git Hints (Web Page)
Useful recipes for working with git and GitHub.
Download the OpenESPI Virtual Machine (Web Page)
How to retrieve and get virtual machine running
Working with the OpenESPI Virtual Machine (Web Page)
How work with the OpenESPI VM