Atom Elements
Understanding the Atom Elements used for Green Button data
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>
element.
The <feed>
contains a number of items, known as “entries” (<entry>
); feeds and entries both support an extensible set of attached metadata. For example, each <feed>
and <entry>
have a <title>
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>
and <entry>
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>
metadata to reference ESPI elements found in the <feed>
.
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>
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>
child elements.
The <feed>
contains the following Atom metadata elements:
-
<id>
<link>
<title>
<published>
<updated>
<entry>
All of the above <feed>
metadata elements must be present but their order is not defined.
The atom:entry
Element
The <entry>
element represents an individual ESPI entry — acting as a container for metadata and the associated ESPI entry. The <entry>
can appear as a child element to the <feed>
element, or as the top-level element of a stand-alone Atom Entry Document.
The <entry>
contains the following Atom metadata elements:
-
<id>
<link>
<title>
<published>
<updated>
<content>
All of the above <entry>
metadata elements must be present but their order is not defined.
The atom:content
Element
The <content>
element contains an ESPI resource record:
<UsagePoint>
, <MeterReading>
, <ReadingType>
, <IntervalBlock>
, 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>
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>
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>
element content.
The atom:link
Element
The <link>
element defines a reference for an entry or feed to a web resource.
The <link>
contains the following atom metadata attributes:
-
rel="…"
href="…"
type="…"
-
-
The atom:link
rel
Attribute
-
<link>
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"
, ortype="up"
.
-
-
-
The atom:link
href
Attribute
-
The <link href="…">
attribute contains the link’s web resource. <link>
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>
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>
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>
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>
element is a date using the UTC (Z
) date:time format of YYYY-MM-DDThh:mm:ssZ
(e.g.,
or 2024-12-31T18:16:35Z
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.2024-12-31T18:16:34.567890Z
The “atom:updated
Element
The <updated>
element is a date using the UTC (Z
) date:time format of YYYY-MM-DDThh:mm:ssZ
(e.g.,
or 2024-12-31T18:16:35Z
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).2024-12-31T18:16:34.567890Z
Need more help with this? Check-out our Technical Education offerings.