Atom & ESPI

Green Button data files and streams use the Atom Syndication Format Standard to represent structured energy-usage information and retail-customer data in an Extensible Markup Language (XML) format.  The power of the Atom Syndication Format to encode complex data for exchange over REST web services was independently recognized by both the GData (Google) and OData (Microsoft) standards.  Based on this, the OpenADE Task Force adopted this construct for the development of the NAESB Energy Services Provider Interface (ESPI): the Green Button core standard.

Structure of Atom Syndication for ESPI

Green Button data are structured as specific XML elements from the NAESB espi.xsd and NAESB customer.xsd inside XML that is defined by the W3C atom.xsd.  The Atom elements act as “wrappers” around the NAESB Energy Usage and Retail Customer XML data.

For example, look at the <LocalTimeParameters>(from ESPI)  element found wrapped in an <entry>(Atom)/<content>(Atom) pair within this singular <feed>(from Atom)  element.  In this example, the <feed>(from Atom)  is the root of the Green Button data file/stream:

    

<!-- Atom wrapper around the ESPI Resources -->
<feed xmlns="http://www.w3.org/2005/Atom" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:espi="http://naesb.org/espi"
  xsi:schemaLocation=
    "http://www.w3.org/2005/Atom https://greenbuttondata.org/xsd/3_3/atom.xsd
     http://naesb.org/espi https://www.naesb.org/espi.xsd">
  <id>urn:uuid:3d8aed62-26a7-589a-9473-98f02ef82dc2</id>
  <title>Green Button Data</title>
  <updated>2022-05-03T04:00:00Z</updated>
  <link rel="self"
    href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/4a795488feac"
    type="espi-entry/Subscription"/>
  <entry>
    <!-- LocalTimeParameters -->
    <id>urn:uuid:eb4cdb32-6eb7-52c8-a1e3-b14f93dedd79</id>
    <link rel="self"
      href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/LocalTimeParameters/8fc3a2ea413e"
      type="espi-entry/LocalTimeParameters"/>
      <link rel="up"
        href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/LocalTimeParameters"
        type="espi-feed/LocalTimeParameters"/>
    <link rel="related"
        href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/RetailCustomer/927ca70a14be/UsagePoint/1feb6f7cf56e"
        type="espi-entry/UsagePoint"/>
      <title>DST For Eastern Time in North America</title>
      <content>
        <!-- one of many ESPI Resources -->
        <espi:LocalTimeParameters>
          <espi:dstEndRule>B40E2000</espi:dstEndRule>
          <espi:dstOffset>3600</espi:dstOffset>
          <espi:dstStartRule>360E2000</espi:dstStartRule>
          <espi:tzOffset>-18000</espi:tzOffset>
        </espi:LocalTimeParameters>
      </content>
      <published>2022-05-03T04:00:00Z</published>
      <updated>2022-05-03T04:00:00Z</updated>
  </entry>
 ...
</feed>
Feed or Entry

Each <feed>(from Atom) can contain multiple <entry>(Atom)/ elements that each can contain an ESPI Resource like <LocalTimeParameters>(from ESPI), <UsagePoint>(from ESPI), and others.

However, if only a single <entry>(Atom)/ is being sent—requested by an application programming interface (API) call—then <entry>(Atom)/ can be used as the root of the Green Button data stream instead of using the <feed>(from Atom) as the root (with all its metadata overhead).

Links of an Atom Feed

You will notice there are many <link>(from Atom) elements inside the singular <feed>(from Atom)  element.  Each <link>(from Atom) has the following attributes:

  • rel= to denote the <link>(from Atom) relates to the <entry>(Atom)/ or to the <feed>(from Atom) in-which it is found.
    • Each <feed>(from Atom) has several <link>(from Atom) elements as-does each<entry>(Atom)/ element.
          
  • href= to define the path to-which the <link>(from Atom) is related (rel) in that <entry>(Atom)/ or <feed>(from Atom) .
    • It is important to note that the structure of the URL must follow the ESPI Standard and
    • the URL must be absolute (not relative); thus containing a full path with the https://.
          
  • type= to denote the relationship of the data:
    • espi (usage data) or customer (identifying data)…
      • feed (a collection of points) or entry (a single point)
    • the ESPI Resource being referenced…
      • <LocalTimeParameters>(from ESPI), <UsagePoint>(from ESPI), <MeterReading>(from ESPI), <IntervalBlock>(from ESPI), etc.

   
The ESPI Standard documentation describes what’s needed for a given ESPI Resource.

Namespaces for Atom and ESPI

XML functions by having defined namespaces for the elements that comprise a file/stream of data.

Namespaces allow programmers to keep one definition separate from another.

One dictionary may define the word “bonnet” to be “a hat worn by a person” whereas another dictionary may define it to be “the hood of an automobile.”  Namespaces prevent one definition from encroaching upon another definition in an XML context.

Since Atom is the wrapper around ESPI Resources, we give Atom a default namespace: xmlns (for XML NameSpace).

We then explicitly define the ESPI namespace: xmlns:espi (we would instead define xmlns:cust for the Retail Customer, identifiable-information data, if our example was for those data).

You’ll note in our examples that there is also a namespace for “XMLSchema-instance” named xmlns:xsi that covers the standard definitions of what comprise XML in the first place.  Tools usually know those definitions anyway but it’s good practice to explicitly keep it separate.

Lastly, we try to help programmers with our examples by referencing the actual namespace dictionaries we use: an XML Schema Definition file, or XSD, is where the elements get their definitions.  We include the schema locations for those XSDs in our examples.  This allows a programmer to simply open an XML file with their development tools and ensure each element meets the standardized definitions.

We place the xsi:schemaLocation attribute in the <feed>(from Atom) root element:

xsi:schemaLocation=
  "namespace1 web-location-of-XSD-file-1
   namespace2 web-location-of-XSD-file-2">

    … as this:

xsi:schemaLocation=
  "http://www.w3.org/2005/Atom https://greenbuttondata.org/xsd/3_3/atom.xsd
   http://naesb.org/espi https://www.naesb.org/espi.xsd">

Despite http://www.w3.org/2005/Atom and http://naesb.org/espi having the the look-and-feel of actual web-location links (web-location links are “uniform resource locators,” or “URLs”), they are not links to the XSDs.  They are simply namespaces (uniform resource identifiers, or URIs).  The URLs that follow those namespaces are actual web links.

The namespace resources can be found at the true web links that follow after those namespaces in the example, above.  The namespaces could have readable names like JaneSmith but they would not be universally unique.  There are other, more-defined, unique, non-URL representations (uniform resource names, or URNs) that could be used instead but often (not always) there is additional information about versioning and authors at the non-resource namespace when it is a URL (web link); so many XML schema designers prefer to use a web link for the namespace even if it is a bit confusing for people not familiar with XML namespaces.

Namespaces defined at Root or Inline

Below, is a smaller example of the namespaces used two different ways:

  1. defined in the <feed>(from Atom) (root of the XML file/stream) and
  2. defined in the enclosed <content>(from Atom element (e.g., <LocalTimeParameters>ESPI) in-which it is a different namespace, inline.

Neither method is better than the other; it’s a matter of programming preference.  You will find our examples both ways and often we use the method that makes it easiest to show you something important in the fewest number of lines for a given example:

    

<!-- Namespace in Feed -->
<feed xmlns="http://www.w3.org/2005/Atom" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:espi="http://naesb.org/espi"
    xsi:schemaLocation=
      "http://www.w3.org/2005/Atom https://greenbuttondata.org/xsd/3_3/atom.xsd
       http://naesb.org/espi https://www.naesb.org/espi.xsd">
    <id>urn:uuid:3d8aed62-26a7-589a-9473-98f02ef82dc2</id>
    <title>Green Button Data</title>
    <updated>2022-05-03T04:00:00Z</updated>
    <link ... />
    <link ... />
    <entry>
        <!-- LocalTimeParameters -->
        <id>urn:uuid:eb4cdb32-6eb7-52c8-a1e3-b14f93dedd79</id>
        <link ... />
        <link ... />
        <link ... />
        <title>DST For Eastern Time in North America</title>
        <content>
        
            <!-- ESPI namespace defined at root (xmlns:espi)
                    and referenced in the element and each child  -->
            <espi:LocalTimeParameters>
                <espi:dstEndRule>B40E2000</espi:dstEndRule>
                <espi:dstOffset>3600</espi:dstOffset>
                <espi:dstStartRule>360E2000</espi:dstStartRule>
                <espi:tzOffset>-18000</espi:tzOffset>
            </espi:LocalTimeParameters>
        
        </content>
        <published>2022-05-03T04:00:00Z</published>
        <updated>2022-05-03T04:00:00Z</updated>
    </entry>
   ...
</feed>