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="…" attribute2="…">…</element>

or

<element attribute1="…" attribute2="…"/>

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

The NAESB REQ.21 ESPI  standard (the core of the “Green Button” technology) uses the Atom standard to provide relationships for the individual ESPI elements in the feed and entries.  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 in the ESPI data 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 metadata elements must be present in the ESPI element entry 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.)

The “atom:id” Element

The <id>(from Atom)  element 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 is 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 (street address, customer’s name, meter number, etc.) in the <title>(from Atom)  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",
      • rel="up", or
      • rel="related".

    

    • The atom:link “href” Attribute

The 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.

    

    • 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:

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

✏️ Note:  For a Retail Customer file/stream that includes a <link>(from Atom)  to a billing image—like a PDF document—the type should specify the bill-image type (e.g., type="application/pdf").

✏️ Note:  For Green Button Certified℠ implementations, there is a Certification Identifier (CertID) <link>(from Atom)  in each output file/stream with 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).