Green Button Alliance Logo

Atom Elements

The Atom Syndication Format Standard (Atom) is an XML-based document formatting standard that describes lists of related information.  The related information is contained in a single <feed>(from Atom)  element.

The <feed>(from Atom)  contains a number of items, known as “entries” (<entry>(from Atom) ); feeds and entries both support an extensible set of attached metadata.  For example, each <feed>(from Atom)  and <entry>(from Atom)  have a <title>(from Atom)  element providing metadata about the feed or entry.

Elements are represented visually (and programmatically) in the files/streams by:

<element attribute1="attribute content 1" attribute2="attribute content 2">element content</element>

… or without element content… 

<element attribute1="attribute content 1" attribute2="attribute content 2"/>

(where names are used in place of element and attribute; more on that, below).

In addition to the NAESB REQ.21 ESPI  standard (the core of the “Green Button” technology), Green Button uses the Atom Syndication Format standard to provide relationships for the individual ESPI elements in the Atom <feed>(from Atom) and  <entry>(from Atom) elements.  This reduces the amount of data in a feed: data only need to be provided once.  This is done by using the Atom <link>(from Atom) metadata to reference ESPI elements found in the <feed>(from Atom) .

For examples of Atom’s relationship to ESPI for Green Button data, see our page about Atom & ESPI.

Atom Metadata Elements

The atom:feed Element

The <feed>(from Atom) is the top-level element of ESPI data — acting as a container for metadata and ESPI data associated with the feed.  It contains a set of metadata followed by one or more <entry>(from Atom)  child elements. 

The <feed>(from Atom)  contains the following Atom metadata elements:

    • <id>(from Atom)
    • <link>(from Atom)  
    • <title>(from Atom)  
    • <published>(from Atom)  
    • <updated>(from Atom)  
    • <entry>(from Atom)  

All of the above <feed>(from Atom)  metadata elements must be present but their order is not defined.

The atom:entry Element

The <entry>(from Atom)  element represents an individual ESPI entry — acting as a container for metadata and the associated ESPI entry.  The <entry>(from Atom)  can appear as a child element to the <feed>(from Atom)  element, or as the top-level element of a stand-alone Atom Entry Document.

The <entry>(from Atom) contains the following Atom metadata elements:

    • <id>(from Atom)
    • <link>(from Atom)  
    • <title>(from Atom)  
    • <published>(from Atom)  
    • <updated>(from Atom)  
    • <content>(from Atom)  

All of the above <entry>(from Atom) metadata elements must be present but their order is not defined.

The atom:content Element

The <content>(from Atom) element contains an ESPI resource record:

<UsagePoint>(from ESPI) , <MeterReading>(from ESPI) , <ReadingType>(from ESPI) , <IntervalBlock>(from ESPI) , etc.

In other words: it contains other elements; specifically, this Atom element contains an ESPI element — it is a wrapper for ESPI.

The atom:id Element

The <id>(from Atom)  element content conveys a permanent, repeatable, unique identifier for an entry or feed.  The ESPI standard requires this identifier to use the UUID format as specified in RFC 4122 using a Version 3 or Version 5 -generated UUID in the format urn:uuid:xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx with a DCE 1.1, ISO/IEC 11578:1996 Variant flag, per RFC 4122.  See our page on Generating Persistent UUIDs for more detail.

The “atom:title” Element

The <title>(from Atom) element content contains a text string that conveys a human-readable title for an entry or feed.  The ESPI standard requires that there is no Personally Identifiable Information (i.e., no street address, no customer’s name, no meter number, etc.) in the <title>(from Atom) element content.

The atom:link Element

The <link>(from Atom)  element defines a reference for an entry or feed to a web resource.  

The <link>(from Atom) contains the following atom metadata attributes:

    • rel="…"
    • href="…"
    • type="…"

 

    • The atom:link rel Attribute

<link>(from Atom)  elements MUST have a rel= attribute that indicates the link’s relationship to the contents of the href= attribute, which contains a web resource.  The ESPI standard defines the acceptable values for the rel= attribute as:

      • rel="self",
      • href="related", or
      • type="up".

    

    • The atom:link href Attribute

The <link href="…"> attribute contains the link’s web resource.  <link>(from Atom) elements MUST have an href= attribute, whose value MUST be an accessible web-resource address.  Further, it MUST be universally accessible.  In other words: it shall be an absolute URL, not a relative URL.  Absolute URLs begin with the protocol used for the connection and the domain hosting the application programming interface (API)
(e.g., "https://www.somewhere.com/…").

    

    • The atom:link type Attribute

The type= attribute is an advisory media type and indicates the type of representation that is expected to be returned when the value of the href= attribute is accessed.  <link>(from Atom)  elements MUST have a type= attribute.  The ESPI standard defines the acceptable values for the type= attribute as:

      • <link type="espi-entry/{ESPI Energy Resource name}"/>,
      • <link type="espi-feed/{ESPI Energy Resource name}"/>,
      • <link type="cust-entry/{ESPI Energy Resource name}"/>, and
      • <link type="cust-feed/{ESPI Energy Resource name}"/>.

✏️ Note:  For a Retail Customer file/stream that includes a <link>(from Atom)  to a bill image — like a PDF document — the link should specify the bill-image type:

e.g., <link href="https://bills.utility.com/…/2025-01-31-bill.pdf" rel="related" type="application/pdf"/>.

✏️ Note:  For Green Button Certified℠ implementations, there is a Certification Identifier (CertID) <link>(from Atom)  in each output file/stream and the type will be text/html:

e.g., <link href="https://cert.greenbuttonalliance.org/certificate/5a3b806d-0c69-5443-bc9d-0b8d6bddb152" rel="related" type="text/html"/>.

The atom:published Element

The <published> (from Atom) element is a date using the UTC (Z) date:time format of YYYY-MM-DDThh:mm:ssZ (e.g., 2024-12-31T18:16:35Z or 2024-12-31T18:16:34.567890Z if decimal-fractions of seconds are desired), with no offset value, indicating an instance in time associated with when the feed or entry was created.

The “atom:updated Element

The <updated> (from Atom element is a date using the UTC (Z) date:time format of YYYY-MM-DDThh:mm:ssZ (e.g., 2024-12-31T18:16:35Z or 2024-12-31T18:16:34.567890Z if decimal-fractions of seconds are desired), with no offset value, indicating an instance in time associated with when a feed or entry was significantly modified in the opinion of the Data Custodian (the utility providing the data).

   

Need more help with this?  Check-out our Technical Education offerings.