From: Heiko Theissen, SAP:

 

At the Grid-Interop 2011, we discussed the use of atom:link elements with rel="up" in the Green Button file format. These links are meant to point from an atom:entry (e.g., /UsagePoint/1/MeterReading/1) to its hierarchically superordinate atom:entry (e.g., /UsagePoint/1), and we came to the conclusion that they should use, e.g., href="/UsagePoint/1", whereas in the examples given in the NAESB draft they use href="/UsagePoint/1/MeterReading", i.e., they point to a collection, not to an entry.

On my flight home, I have thought about this question again, and I now consider our conclusion premature.

Although up-links that point to an entry make it easier to select the hierarchically superordinate atom:entry, they prevent the other direction, making it impossible to select the hierarchically subordinate entries. For example, an <atom:link rel="up" href="/UsagePoint/1"/> would not only be found in the atom:entries for the MeterReadings, but also in the atom:entries for the ElectricPowerUsageSummaries, and these two kinds of subordinate entries cannot be distinguished without decomposing the URLs in the hrefs, what we wanted to avoid in the first place.

On the other hand, up-links that point to collections make it possible to elegantly select (with the help of XPath expressions) both the superordinate and the subordinate elements. Given an atom:entry element, we can select
• the hierarchically superordinate element by putting the context on the given atom:entry's up-link and evaluating the XPath expression
../../atom:entry[atom:link[@rel="related"]/@href=current()/@href]
(we select the entry whose related-link points to the same collection as the current up-link)
• the hierarchically subordinate elements of a given type (e.g., the MeterReadings, but not the ElectricPowerUsageSummaries) by putting the context on the corresponding related-link and evaluating the XPath expression
../../atom:entry[atom:link[@rel="up"]/@href=current()/@href]
(we select the entries whose up-links point to the same collection as the current related-link).
These selections work for 1:n relationships between super- and subordinate elements, where both the related-link and the up-link have type="application/atom+xml;type=feed".

But there are also 1:1 relationships
• either hierarchically from a super- to a subordinate element (e.g., the ElectricPowerQualitySummary subordinate to a UsagePoint) where both links have type="application/atom+xml;type=entry"
• or associations independent of the hierarchy (e.g., the ReadingType related to a UsagePoint), here the related-link has type="application/atom+xml;type=entry" (but the up-link of the ReadingType points to the feed of ReadingTypes and has type="application/atom+xml;type=feed").
In the case of such 1:1 relationships, analogous XPath expressions to the ones shown above can be used, where [@rel="up"] is replaced by [@rel="self"] (and the parenthesised "we select" remarks should read "the same entry" instead of "the same collection").

To summarise: I now believe that the up-links given in the NAESB draft are perfectly valid.

heiko.theißen (4/12/2012 11:03 AM): The way I would expect the atom:links to be interpreted can be expressed in the following XSLT templates:

 

<xsl:template match="atom:link[@rel='related']">
  <xsl:variable name="target" select="ancestor::atom:feed/atom:entry/atom:link
    [@rel!='related' and @href=current()/@href]"/>
  <xsl:choose>
    <xsl:when test="$target/@rel='self' and
      $target/../atom:link[@rel='up']/@href=../atom:link[@rel='self']/@href">
      <xsl:apply-templates select="$target/.." mode="hierarchical-relation-1-1"/>
    </xsl:when>
    <xsl:when test="$target/@rel='self'">
      <xsl:apply-templates select="$target/.." mode="non-hierarchical-relation-1-1"/>
    </xsl:when>
    <xsl:when test="$target">
      <xsl:apply-templates select="$target/.." mode="relation-1-n"/>
    </xsl:when>
  </xsl:choose>
</xsl:template>

<xsl:template match="atom:link[@rel='up']">
  <xsl:variable name="target" select="ancestor::atom:feed/atom:entry/atom:link
    [@rel!='up' and @href=current()/@href]"/>
  <xsl:choose>
    <xsl:when test="$target/@rel='self'">
      <xsl:apply-templates select="$target/.." mode="hierarchical-relation-1-1"/>
    </xsl:when>
    <xsl:when test="$target">
      <xsl:apply-templates select="$target/.." mode="relation-1-n"/>
    </xsl:when>

    <!-- There are no up-links for non-hierarchical relations. -->
  </xsl:choose>
</xsl:template>

heiko.theißen (4/12/2012 10:54 AM): I think that the usage of these links is not yet uniformly observed in all the Green Button examples that are "out there". The sample data by SDG&E http://www.greenbuttondata.org/greendevelop.html are correctly linked, they seem to have been copied from the original sample https://collaborate.nist.gov/twiki-sggrid/pub/SmartGrid/GreenButtonInitiative/GETBatchSampleEUI.xml with only the IntervalBlock contents replaced.
 
I found one other set of sample data by PGE http://pge.com/includes/docs/xml/shared/greenbutton/XML%20Sample%20Residential%20Electric%20Usage%2007072011%2012032011.zip, and here the atom:links are not used in the way I expect:
•         The UsagePoint entry contains a related-link to a MeterReading entry whereas it should link to a MeterReading feed.
•         The MeterReading entry should contain an up-link to the MeterReading feed /UsagePoint/xxx/MeterReading, but it does not.
•         The MeterReading entry contains a related-link to an IntervalBlock entry whereas it should link to an IntervalBlock feed.
•         The IntervalBlock entry should contain an up-link to the IntervalBlock feed /UsagePoint/xxx/MeterReading/yyy/IntervalBlock, but it does not. (There are no up-links at all in the sample.)

The hierarchial relationship between the entries in PGE's sample can only be derived from the internal structure of the hrefs, by splitting these URIs at the slashes. But in my opinion this should not be done, since these URIs are assumed to be opaque.

The usage of atom:links is probably irrelevant to "Green Button apps" that only visualize the IntervalReadings for one UsagePoint. But the issue should become relevant as more complex apps are developed. A common understanding about the links between producers of Green Button data (energy companies) and consumers (app developers) is perhaps not yet reached.

martin.burns (1/31/2012 2:25 PM):