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 "feeds".  Feeds contain a number of items, known as "entries"; feeds and entries both support an extensible set of attached metadata.  For example, each feed and entry have a "title".

Elements are represented visually (and programatically) 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 ESPI standard 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" 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.

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 atom:entry child elements. 

The atom:feed contains the following atom metadata elements

• • atom:id
  • atom:link
  • atom:title
  • atom:published
  • atom:updated
  • atom:entry

All of the above feed metadata elements must be present in the ESPI data 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 atom:entry contains the following atom metadata elements:

• • atom:id
  • atom:link
  • atom:title
  • atom:published
  • atom:updated
  • atom:content

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> element contains an ESPI resource record (UsagePoint, MeterReading, ReadingType, IntervalBlock, etc.)

• The "atom:id" Element

The <id> element conveys a permanent, repeatable, unique identifier for an entry or feed.  The ESPI standard requires this identifier to use UUID as specified in RFC 4122 using a Version 3 or 5 generated UUID in the format "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".

• The "atom:title" Element

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

• The "atom:link: Element

The <link> element defines a reference for an <entry> or <feed> to a Web resource.  

The atom:link contains the following atom metadata attributes:

• • atom:link rel
  • atom:link href
  • atom:link type

• • The "rel" Attribute

atom: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 atom:link rel attribute as:

• • • "self",
    • "up", or
    • "related".

• • The "href" Attribute

The href attribute contains the link's Web resource.  atom:link elements MUST have an href attribute whose value MUST be an accessible Web Resource address.

• • The "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.  The ESPI standard defines the acceptable values for the type attribute as:

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

• The "atom:published" Element

The <published> element is a date using the UTC date:time format with no offset value indicating an instance in time associated with when the feed or entry was created.

• The "atom:updated" Element

The <updated> element is a date using the UTC date:time format with no offset value indicating an instance in time associated with when a feed or entry was significantly modified in the opinion of the utility.