Frequently Asked Questions

These Frequently Asked Questions (FAQs) are a work-in-progress culmination of questions we often get from Utility representatives, Third Party developers, Customers of both, and commissions and consumer advocates.

For less-technical information, look to our non-technical Informational FAQs page.
   

Yes, the standards are open: they are free to implement, there is no mandatory registration, and there are no licenses to sign or royalties to pay.

The Green Button data format uses the following industry data format standards:

The Green Button standard uses the following data access and communication security standards to protect access to the data and during transmission:

All of the above are free to use and their licenses are generally permissive.

For a more-complete list of the standards, see the next FAQ on this page.

The printed standard is free for NAESB members; non-members may purchase a copy of the ESPI business practices document for US$250, but the ESPI XML Schema Definitions are free and available under the Apache 2.0 license.

Implementing a Server (i.e., “Data Custodian”) or a Client (i.e.,“Third Party”) app or service does not incur royalties or pay-to-use costs.

Unlike many technology associations, the Green Button Alliance does not force anyone to become a Green Button Alliance member to use the compilation of standards, to purchase technical education, to use our developer resources, to participate in the OpenADE technical committee, or to have an implementation Certified — though there is a cost for Certification testing and issuance of the Certification; commensurate with our costs to perform the work as a nonprofit, charitable organization.

More about Green Button

The Green Button data format uses the following industry data format and security standards:

W3C Standards
Internet Engineering Task Force (IETF)
North American Energy Standards Board (NAESB)
The implementer’s resource server APIs use OAuth 2.0 access tokens to validate authorization.  When accessing the implementer’s website using a browser, a Customer Authentication is performed based on the implementer’s standard authentication process.

There are several ways Green Button data are kept secure:

Downloaded Data
  • Utilities provide secure web portals for their Customers.  Green Button data that is downloaded from a secure portal is no different than a PDF bill downloaded from the same portal: the level of the portal’s security is up-to the Utility.
  • Once the data are downloaded:
    • The Usage file should contain no personal information: no meter numbers, no account numbers, no addresses, no account-owner information, … nothing but usage data and, perhaps, the associated cost being billed.  Essentially, if the file were to be stolen and posted to the web, nothing in the file should point to the data owner.  If your Utility’s exports have personal information in the Usage file, contact them to let them know they are not in-compliance with the Green Button standards.
    • The Retail Customer file (if a Utility provides it) could contain quite a bit of personal information: addresses, meter numbers, and much more.  However, it will not contain the Usage data.  Thus, while the file has a Customer’s address and other details there’s no way someone could know how-much electricity that Customer used.
Connected Data
  • When a Customer allows data to be shared with a Third Party app or provider of services (e.g., carbon-footprint app, solar-array installation company), they choose what to share: Usage, Retail Customer, electricity, natural gas, water, historical data, interval size, on-going sharing, etc.  The security level is what the Customer selects or allows.
  • While the data are in transit:
    • The Utility and the Third Party must both have well-known Certificate Authority -issued HTTPS Certificates of a minimum level of encryption (depending on Green Button versions implemented).  Further, Transport Layer Security (TLS) must be supported on both of their servers (again, depending on the Green Button versions implemented).
    • Each servers can use the other server’s public-side certificate to verify that there is no “man in the middle” eavesdropping. 
  • When data are requested:
    • The important term here is “requested” because when a Third Party wants data, they must request the data and the Utility will then provide the data only if the Third Party is both qualified (onboarded with that Utility to do transactions) and authorized (by the Customer); including with a non-expired and non-revoked relationship with that Customer.
    • Additionally, Third Parties are never given keys to the data; they are never allowed to enter into the databases of the Utility.  The Third Party presents a token (a very long number-letter combo) to the Utility when requesting data.  Each token is granted by the Utility to represent the exact sharing relationship with the Customer before data requests are allowed.  Upon receiving the token, the Utility can gather the data and give it to the Third Party’s server (or provide a location to go get it, if the Utility needs more time to assemble it all).
    • The Utility can again check all security to ensure only that Third Party is getting the data. 

This question is so common that we go into a bit of history and depth on this one…

XML is based on the same structure as HTML — i.e., Standard Generalized Markup Language (SGML), which itself has its roots back to 1969 and was standardized by ISO in 1986.  XML was derived from SGML in the late 1990s.  Some programmers today think it’s too old.  However, both HTML (the underpinning of the world-wide web) and XML are still used extensively across the world today, roughly 30 years later.

Why was XML chosen?

XML was chosen for the data structure of Green Button because:

    • it’s flexible,
    • its layout is human-readable,
    • off-the-shelf parsers and software development kits know how to process it,
    • the syntax is so clean that is it difficult to make mistakes that aren’t easily visible, and
    • most of all: XML Schema Definitions (XSDs) could be written to ensure development tools could help people meet the standard.

Comma-Separated Value (CSV) files lack any sort of definition for what goes into a column/row or how the data are represented and scaled.  CSV can be opened like a spreadsheet but there’s no consistency between the output of one utility and another.  Every software tool designed to read the data must be customized to understand how that particular utility chose to represent 123.456 kWh and the intervals involved.

At the time, JSON didn’t have these definitions either; neither did other available text formats that used spacing and fixed sequencing. 

JSON is a structured format, like XML, so shouldn’t it be just as easy to use if the Green Button Alliance defines the JSON format?

In the years since choosing XML, many parsers and development tools — and the servers that drive web applications — went-ahead and built in support for JSON, like they had for XML.  There is now even an XSD-like schema definition for JSON files.  However, JSON Schema was only created in June of 2022 and it’s not a full standard yet (at least at the time of this writing). 

Use of atom.xsd, espi.xsd, and customer.xsd allows development tools to help programmers be assured of the formats for data.  For example:

When a Green Button file of data is created or updated, a date and time is inserted by the Utility (or other Data Custodian) in the field that represents when it was updated:  <updated>.

The atom.xsd, which acts as the relational wrapper around the ESPI content, defines atom:dateTimeType to be based on xs:dateTime (the official XML format, which is based on the ISO 8601 international standard of yyyy-mm-ddThh:mm:ss.sZ or the variants therein defined).  If a programmer puts 2030-12-31 into the <updated> element of a data file, the development tools will inform the programmer that they are missing the Time component; a requirement of that data type.  They would then need to input a time too, like this:
   <updated>2030-12-31T15:12:00Z</updated>.

Now that JSON Schema exists, why doesn’t it replace XML with JSON for Green Button?

The young age of JSON Schema, and that Schema’s lack of full acceptance, are important factors but there are two greater factors:

    • Use of the Atom syndication format allows data files or streams (DMD or CMD, respectively) to be relational—like a database—in a flat file format.  The Atom encompasses the ESPI Energy Usage and ESPI Retail Customer data and allows each item to be linked/associated with other items.  It can vastly reduce the redundancy of including units, time zones, and other information over and over again in each reference.  Atom also allows the entire file/stream of data to be downloaded/sent or can allow just a single entry of data to be downloaded/sent for even-faster handling.  Atom is in XML, just like the two ESPI formats.
    • There are well-over 100 utility implementations (as-of the time of this writing) providing Green Button data in the XML format to well-over 100 million people.  If we switch to JSON—or migrate Utilities to it—then each Third Party app/solution provider must support both XML and JSON to be able to read what is provided by each utility.

XML files are so-much larger than JSON files, isn’t that an issue?

When 128kbps was the norm in “broadband,” HTML, XHTML (XML-encoded HTML), and XML itself were used extensively without issue because it compresses efficiently.  Today, with 1Gbps or greater being commonplace between server-to-server communications—like that used for CMD—and with even-better compression techniques, XML’s size poses no issue in transit.  Even at rest, the files can compress very well to limit their use of storage (which itself has become plentiful and cheap, going from GB to TB for a fraction of the cost).

App development is open to anyone and is operating-system independent.  As for producing mobile applications: Green Button Connect My Data (CMD) is a communication between your server and the utility’s server.  Therefore, a client application on a mobile device would need to communicate through your server; not directly to the utility.

That security mechanism ensures that your server and the utility’s server “know each other” by being able to access each other’s public HTTPS certificates.

Additionally, mobile clients are not inherently secure and require the authorization code flow to use Proof Key for Code Exchange (PKCE), which is not-yet available for Green Button implementations (though a topic of discussion in the OpenADE Task Force).

Therefore, the initial authorization a customer makes — to allow you to obtain their data directly from the utility — should be made from a computer browser (again, via your server and the utility’s server).

More FAQs are coming soon (likely tomorrow).

Are you a Developer in need of more than just answers to FAQs? 
Take a look at our Developer Resources, here…

Developer Resources