rNews 0.5: Implementation Guide

Embedding rNews using RDFa

In our introduction to rNews, we provided an exhaustive rundown of the entire rNews standard. We presented the data model, enumerated the classes and used this knowledge to completely model a sample article. In this document, we're going to take this model, dramatically simplify it, and embed the result in HTML using RDFa. d When you're done reading this, you'll be ready to deploy rNews on your site.

A Simpler Sample

In our introduction we wanted to show you everything that rNews could do, so we used a sample article of great complexity. In this section we're more interested in the nuts and bolts of implementing rNews as RDFa in HTML, so we're going to simplify our example and focus on the essential properties. Remember how we said the rNews classifies its attributes and relations into core and power, well from here on out we're only going to consider the core properties. Also we're going to remove all unecessary metadata from the example article.

So after paring back our article we are left with the following page.

Figure 1: The simplified version of our sample article.
Behind the scenes, this article is written down in the following HTML minus styling information and long strings that we've removed for clarity. 
      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">  
      <html>
      <head></head>
      <body>
         <div>
          <div>
             <div>Allies Are  Split...</div>
            <div>NATO Takes  Command</div>
            <div>
              <img  src="img/libya_sample_reuters.jpg"/>
              <div>Credit: Goran Tomasevic/Reuters</div>
               <div>Rebel fighters  take...</div>
            </div>
            <div>By STEVEN LEE  MYERS</div>
            <div>WASHINGTON  | March 24, 2011</div>
            <div>
              <p>Having  largely succeeded...</p>
            </div>
            <div>
              <p><a  href="http://www.nytimes.com/content/help/rights/copyright/copyright-notice.html">
                 © Copyright  2011
               </a><span>The New York  Times  Company</span></p>
              <p><a  href="http://www.nytimes.com/ref/membercenter/help/agree.html">
                 Disclaimer
               </a></p>
             </div>
          </div>
           <div>
            <div>
              <div>Section</div>
              <div>World</div>
            </div>
            <div>Tags</div>
             <div>
              <div>
                <div>People</div>
                <div>Qaddafi, Muammar  el-</div>
              </div>
            </div>      
            <div>
              <div>Discussion  (3)</div>
              <div>
                <div>So the question  is..."</div>
                <div>
                <a  href="http://timespeople.nytimes.com/view/user/27242827/activities.html">Chuck</a></div>
                <div>March 25th,  2011 8:27 am</div>
              </div>
            </div>
          </div>
         </div>
      </body>
      </html>
Figure 2: The (slightly abridged) version of the HTML powering our sample article.

Now that we have this HTML article, we need some RDF to embed using RDFa. Below, we've simplified the the model we produced in our introduction to rNews. We'll be working with this simplified model for the rest of this tutorial. 

   
    @prefix rnews: <http://iptc.org/std/rNews/2011-05-17#> .
    
    <http://dev.iptc.org/rnews/sample_story.html>
      a rnews:Article ;
      rnews:dateCreated "2011-03-24" ;
      rnews:dateline "WASHINGTON" ;
      rnews:headline "Allies Are Split on Goal and Exit Strategy in Libya" ;
      rnews:alternativeHeadline "NATO Takes Command" ;
      rnews:description "The questions about the command mirrored the strategic divisions over how the coalition will end the operation." ;
      rnews:language "en" ;
      rnews:thumbnailUri <http://graphics8.nytimes.com/images/common/icons/t_wb_75.gif> ;
      rnews:copyrightedBy <http://www.nytimes.com> ;
      rnews:hasSource <http://www.nytimes.com> ;
      rnews:providedBy <http://www.nytimes.com> ;
      rnews:copyrightNoticeUri <http://www.nytimes.com/content/help/rights/copyright/copyright-notice.html> ;
      rnews:usageTermsUri <http://www.nytimes.com/ref/membercenter/help/agree.html> .       
      rnews:createdBy <http://topics.nytimes.com/topics/reference/timestopics/people/m/steven_lee_myers/> ;
      rnews:discussedBy <http://community.nytimes.com/comments/www.nytimes.com/2011/03/25/world/africa/25policy.html?permid=1#comment1>,       
      rnews:taggedBy <http://data.nytimes.com/91178019641520997503> ;
      rnews:illustratedBy <http://graphics8.nytimes.com/images/2011/03/25/world/africa/Policy/Policy-articleLarge.jpg>
      
    <http://graphics8.nytimes.com/images/2011/03/25/world/africa/Policy/Policy-articleLarge.jpg>
      a rnews:Media ;
      rnews:mediaType "Picture" ;
      rnews:mediaTypeUri <http://cv.iptc.org/newscodes/mediatype/picture> ;
      rnews:description "Rebel fighters take cover during a shelling near Ajdabiyah, Libya on Thursday." ;
      rnews:createdBy <http://blogs.reuters.com/goran-tomasevic/> ;      
      rnews:copyrightedBy <http://www.reuters.com> ;
      rnews:hasSource <http://www.reuters.com> ;
      rnews:providedBy <http://www.reuters.com> .
      
    <http://community.nytimes.com/comments/www.nytimes.com/2011/03/25/world/africa/25policy.html?permid=4#comment4>
      a rnews:Comment ;
      rnews:commentText "So the question is: Why is Secretary of Defense Hillary Clinton speaking as the Defense Secretary..." ;
      rnews:commentTime "2001-03-25T08:27:00" ;
      rnews:createdBy <http://timespeople.nytimes.com/view/user/27242827> . 
      
    <http://blogs.reuters.com/goran-tomasevic/>
      a rnews:Person ;
      rnews:name "Goran Tomasevic" . 
      
    <http://topics.nytimes.com/topics/reference/timestopics/people/m/steven_lee_myers/>
      a rnews:Person ;
      rnews:name "STEVEN LEE MYERS" . 
    
    <http://timespeople.nytimes.com/view/user/27242827>
      a rnews:person ;
      rnews:name "Chuck" 
      
    <http://data.nytimes.com/91178019641520997503>
      a rnews:Person ;
      rnews:name "Qaddafi, Muammar el-" . 
 
    <http://www.nytimes.com>
      a rnews:Organization ;
      rnews:tickerSymbol: "NYSE NYT" ;
    
    <http://www.reuters.com>
      a rnews:Organization ;
      rnews:name "Reuters" .
Figure 3: The simplified model we're goign to embed using RDFa.
Lets Embed

We've got an HTML document, and we've got an RDF model of the data in that document. It's time to do some embedding. To keep things simple, we'll take a few properties at a time and show how to express them using RDFa. Once we've covered all of the properties we'll show you the final document with all the RDFa in place.

The First Steps

The very first thing we have to do before we can embed anything is to change the <!DOCTYPE> declaration from standard XHTML, to XHTML+RDFa. So we change the first line of our sample HTML document to: 

      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"  "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">

Now we need to declare the rNews XML namespace. To do this we simply change the second line of our sample HTML document as follows: 

      <html  xmlns:rnews=http://iptc.org/std/rNews/2011-05-17#>

Now we need to assert that the primary thing we'll be describing is of type rnews:Article and that it has the name <http://dev.iptc.org/rnews/sample_story.html>. So we modify the third line of the sample HTML document to read: 

      <body about="http://dev.iptc.org/rnews/sample_story.html"  
            typeof="rnews:Article">

Adding the basics

Now that we've poured the foundation, it's time to build. We'll start by embedding the headline, dateline and creation date into our sample article. To do this, we change lines 7 and 15 like so: 

      <div  property="rnews:headline">Allies Are  Split...</div>
  
      <div>
        <span property="rnews:dateline">WASHINGTON</span>  |  
        <span property="rnews:dateCreated" content="2011-03-24">March 24, 2011</span>
      </div>

A couple of RDFa notes:

  • To annotate the rnews:dateline and rnews:dateCreated fields it was necessary to introduce two new <span> elements as containers for the RDFa markup.
  • In RDFa, if an element specifies a content attribute, the value of this attribute overrides the actual content of the element. For instance, to annotate the rnews:dateCreated field we place an xsd:date formatted string, "2011-03-24", in a content attribute within the enclosing <span> element. This is because the enclosed text, "March 24, 2011," is not parseable as an xsd:date.

Applying these notes, we'll now annotate the article's body text, copyright statement, and usage terms as follows: 

        <div property="rnews:body">
          <p>Having largely succeeded...</p>
        </div>
        <div>
          <p>
            <a href="http://www.nytimes.com/content/help/rights/copyright/copyright-notice.html"
               rel="rnews:copyrightNoticeUri">
              © Copyright 2011
            </a>
            <span>The New York Times Company</span>
          </p>
          <p>
            <a href="http://www.nytimes.com/ref/membercenter/help/agree.html"
               rel="rnews:usageTermsUri">
              Disclaimer
            </a>
          </p>
        </div>

Another quick note about RDFa.

The RDFa syntax for expressing RDF triples that have an object type of URI (a.k.a. object triples) is different than the syntax used for RDF triples with an object that is of a literal type (a.k.a. data triples). Data triples are expressed using the property attribute, sometimes with an assist from the content attribute, like so: 

        <div  property="rnews:body">
          <p>Having largely  succeeded...</p>
        </div>
or 
        <div property="rnews:body" content="Having largely  succeeded...">
        </div>
The RDFa syntax for expressing object triples, on the other hand, uses the rel attribute in combination with an href (or src) attribute. For example: 
        <a  href="http://www.nytimes.com/ref/membercenter/help/agree.html" rel="rnews:usageTermsUri">
          Disclaimer
        </a>

Embedding Hidden Metadata

For our next trick, we will embed a brief description of the article along with the article's language and a thumbnail image. "But wait", you say, "that information isn't visible on the article page or hiding anywhere in the HTML document!"

You, of course, are right.

So how do we add this missing metadata? By stashing it in a hidden element such as a <div> or a <span>. You can place such a hidden element anywhere you like, we prefer to hide it at the bottom of the page. So after line 51 in our sample HTML document, we add the following. 

        <div  style="display:none">
          <div property="rnews:description">The questions about the...</div>
            <div property="rnews:language">en</div>
            <div rel="rnews:thumbnailUri" 
                 href="http://http://graphics8.nytimes.com/images/common/icons/t_wb_75.gif"</div>           
        </div>

In this example we chose to use a hidden <div> tag, but you can use any valid XHTML element. That being said, we reccomend the <div> tag simply because it's a short tag and will ever so slightly reduce the footprint of your RDFa markup.

Embedding Multiple Objects

Our next task is to embed our article's provenance information into our hidden div. As you will recall we asserted the following triples in our model. 

    <http://dev.iptc.org/rnews/sample_story.html>
      rnews:copyrightedBy <http://www.nytimes.com> ;
      rnews:hasSource <http://www.nytimes.com> ;
      rnews:providedBy <http://www.nytimes.com> .
    
    <http://www.nytimes.com>
      a rnews:Organization  ;
      rnews:name "The New York Times"
We'll start with the rnews:copyrightedBy triple. To express this in RDFa, we add the following to our hidden <div> 
    <div  style="display:none">
      ...    
      <div  rel="rnews:copyrightedBy">
        <div about="http://www.nytimes.com"  typeof="rnews:Organization"">
          <div property="rnews:name">The  New York Times</div">
        </div">
      </div>
    </div>

The above code snippet asserts that the article <http://dev.iptc.org/rnews/sample_story.html> is rnews:copyrightedBy the Organization <http://www.nytimes.com>. But the mechism for this assertion is a little confusing, so lets take a closer look.

A Note on Scope

The subject asserted for a triple in RDFa depends entirely on scope. Consider the following snippet. 

          
 
            
             
            
Object One
 
            
 
            
               
              
Object Two
Between lines 1-4 and on line 10-12 we are in the scope of <http://example.foo#parent>. Between lines 5-9 we are in the scope of <http://example.foo#child>. When we run this HTML snippet through an RDFa distiller the following triples are parsed. 
          <http://example.foo#parent>
            sample:verbOne "Object 1"
          
          <http://example.foo#child>
            sample:verbTwo "Object 2"
As you can see, RDFa uses the scope of a verb-object pair to determine subject attachment.

But there is one more wrinkle to explain. Let's update our code example ever so slightly. 

        
 
          
           
          
Object One
 
          
          
 
            
 
            
               
              
Object Two
As you can see we've enclosed the subject <http://example.foo#child> in an additional <div> element to which we've added the attribute rel="sample:hasChild". This asserts that the subject of the in the enclosing scope is in a rel="sample:hasChild" with every other resource declared in its scope. So when we run this code snippet through a distiller we get the following RDF. 
          <http://example.foo#parent>
            sample:verbOne "Object 1"
            sample:hasChild <http://example.foo#child>
            
          <http://example.foo#child>
            sample:verbTwo "Object 2"

Returning to our Example...
Now that we've cleared up how RDFa parses nested resources, lets return to marking up our example with rNews.

So we've thus far managed to assert that our article <http://dev.iptc.org/rnews/sample_story.html> is rnews:copyrightedBy the Organization <http://www.nytimes.com>. Now we want to assert that this subject is rnews:providedBy and rnews:hasSource <http://www.nytimes.com> This is easy. Simply add these new relations to the existing <rel> attribute as follows. 

        <div style="display:none">
        ...    
        <div rel="rnews:copyrightedBy rnews:hasSource rnews:providedBy">
        <div about="http://www.nytimes.com" typeof="rnews:Organization"">
          <div property="rnews:name">The New York Times</div">
        </div">
        </div>
      </div>
Marking Up The Byline

Now we're going to combine several of the RDFa techniques we've discussed so far to markup the byline. As you will recall, the original HTML for the byline looks like this. 

    <div>By STEVEN LEE MYERS</div>

And the triples describing the byline are as follows: 

        <http://dev.iptc.org/rnews/sample_story.html>      
        rnews:createdBy <http://topics.nytimes.com/topics/reference/timestopics/people/m/steven_lee_myers/> .
        
        <http://topics.nytimes.com/topics/reference/timestopics/people/m/steven_lee_myers/>
        a rnews:Person ;
        rnews:name "STEVEN LEE MYERS" .

To shoehorn all of this metadata into our sample HTML document, we'll modify line 14 as follows:

  1. Add a <rel="rnews:createdBy"> attribute to the enclosing <div>.
  2. Wrap the text "By STEVEN LEE MYERS" in a new <div> element that declares the name and type of the byline.
  3. Wrap the name "STEVEN LEE MYERS" in a new <span> and add the attribute property="rnews:name"
Following these steps, we end up with the following HTML. 

        <div rel="rnews:createdBy">
        <div about="http://topics.nytimes.com/topics/reference/timestopics/people/m/steven_lee_myers/" typeof="rnews:person">By 
          <span property="rnews:name">STEVEN LEE MYERS</span>
        </div>
        </div>
Marking Up The Concepts

Following a similar approach we can mark up this original HTML for the tag. 

        <div>
          <div>
            <div>People</div>
            <div>Qaddafi, Muammar el-</div>
          </div>
        </div>
With these triples. 
          <http://dev.iptc.org/rnews/sample_story.html>
            rnews:taggedBy <http://data.nytimes.com/91178019641520997503> ;
      
        <http://data.nytimes.com/91178019641520997503>
          a rnews:Person ;
          rnews:name "Qaddafi, Muammar el-" .
Giving us this results. 
        <div rel="rnews:taggedBy">
          <div>People</div>
          <div about="http://data.nytimes.com/91178019641520997503" typeof="rnews:Person">
          <span property="rnews:name">Qaddafi, Muammar el-</span>
          </div>
        </div>

Marking up The Comment

Original HTML: 

          <div>
            <div>Discussion (3)</div>
            <div>
              <div>
                So the question is..."
              </div>
              <div>
                <a href="http://timespeople.nytimes.com/view/user/27242827/activities.html">Chuck</a>
              </div>
              <div>
                March 25th, 2011 8:27 am
              </div>
            </div>
          </div>
Triples: 
        <http://dev.iptc.org/rnews/sample_story.html>
          rnews:discussedBy <http://community.nytimes.com/comments/www.nytimes.com/2011/03/25/world/africa/25policy.html?permid=1#comment1>,       
          
        <http://community.nytimes.com/comments/www.nytimes.com/2011/03/25/world/africa/25policy.html?permid=4#comment4>
          a rnews:Comment ;
          rnews:commentText "So the question is..." ;
          rnews:commentTime "2001-03-25T08:27:00" ;
          rnews:createdBy <http://timespeople.nytimes.com/view/user/27242827> .
Result: 
        <div rel="rnews:discussedBy">
          <div>Discussion</div>
          <div about="http://community.nytimes.com/comments/www.nytimes.com/2011/03/25/world/africa/25policy.html?permid=4#comment4" typeof="rnews:comment">
          <div property="rnews:commentText">So the question is...</div>
          <div rel="rnews:createdBy">
            <span about="http://timespeople.nytimes.com/view/user/27242827" typeof="rnews:person">
            <a href="http://timespeople.nytimes.com/view/user/27242827"
               property="rnews:name">Chuck</a>
            </span>
          </div>
          <div property="rnews:commentTime" content="2001-03-25T08:27:00">March 25th, 2011 8:27 am</div>
          </div>
        </div>

Marking Up The Image

We're going to finish by annotating all of the triples we've asserted concerning the image associated with the article. And In case you forgot, these triples are as follows: 

         
        <http://graphics8.nytimes.com/images/2011/03/25/world/africa/Policy/Policy-articleLarge.jpg>
          a rnews:Media ;
          rnews:mediaType "Picture" ;
          rnews:mediaTypeUri <http://cv.iptc.org/newscodes/mediatype/picture> ;
          rnews:description "Rebel fighters take cover during a shelling near Ajdabiyah, Libya on Thursday." ;
          rnews:createdBy <http://blogs.reuters.com/goran-tomasevic/> ;      
          rnews:copyrightedBy <http://www.reuters.com> ;
          rnews:hasSource <http://www.reuters.com> ;
          rnews:providedBy <http://www.reuters.com> .
          
        <http://blogs.reuters.com/goran-tomasevic/>
          a rnews:Person ;
          rnews:name "Goran Tomasevic" . 
     
        <http://www.reuters.com>
          a rnews:Organization ;
          rnews:name "Reuters" .
The original HTML for the image looks like this. 
          <div>
            <img src="img/libya_sample_reuters.jpg"/>
            <div>Credit: Goran Tomasevic/Reuters</div>
            <div>Rebel fighters take...</div>
          </div>
Using all the tricks we've covered so far, we can embed the above triples into this HTML as follows: 
        <!-- Declaring the Media Object -->
        <div about="http://graphics8.nytimes.com/images/2011/03/25/world/africa/Policy/Policy-articleLarge.jpg"
           typeof="rnews:Media">
          <img src="img/libya_sample_reuters.jpg"/>
          <div>Credit: 
     
          <!-- Declaring the Person Object for the creator  -->
          <span rel="rnews:createdBy">
            <span about="http://blogs.reuters.com/goran-tomasevic/" 
              typeof="rnews:Person">
            <span property="rnews:name">Goran Tomasevic</span>
            </span>
          </span>/
          <span rel="rnews:copyrightedBy rnews:hasSource rnews:providedBy">
          
            <!-- 
            Declaring the Organization Object for coprightHolder/source/provider  
            -->
            <span about="http://www.reuters.com" 
              typeof="rnews:Organization">
            <span property="rnews:name">Reuters</span>
            </span>
          </span>
          </div>
          <div property="rnews:description">Rebel fighters take...</div>
          
          <!-- Adding hidden triples to our image object. -->
          <div style="display:none">
          <div property="rnews:mediaType">Picture</div>
          <div rel="rnews:mediaTypeUri" 
             href="http://cv.iptc.org/newscodes/mediatype/picture" >
          </div>
          </div>
        </div>

Final Assembly

In the examples above, we've demonstrated how to embed rNews triples into HTML documents using RDFa. Now as a parting gift, we'd like to show you what the complete HTML for our sample article looks like once we've embedded all of the triples. 

        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
        <html xmlns:rnews=http://iptc.org/std/rNews/2011-05-17#>
        <head></head>
        <body about="http://dev.iptc.org/rnews/sample_story.html" typeof="rnews:Article" >
        <div>
          <div>
          <div property="rnews:headline">Allies Are Split...</div>
          <span property="rnews:alternativeHeadline">NATO Takes Command</span>
          <div rel="rnews:illustratedBy">
            <div about="http://graphics8.nytimes.com/images/2011/03/25/world/africa/Policy/Policy-articleLarge.jpg"
             typeof="rnews:Media">
            <img src="img/libya_sample_reuters.jpg"/>
            <div>Credit: 
             
              <!-- Declaring the Person Object for the creator  -->
              <span rel="rnews:createdBy">
              <span about="http://blogs.reuters.com/goran-tomasevic/"
                typeof="rnews:Person">
                <span property="rnews:name">Goran Tomasevic</span>
              </span>
              </span>/
              <span rel="rnews:copyrightedBy rnews:hasSource rnews:providedBy">
               
              <!-- 
              Declaring the Organization Object for coprightHolder/source/provider  
              -->
              <span about="http://www.reuters.com"
                typeof="rnews:Organization">
                <span property="rnews:name">Reuters</span>
              </span>
              </span>
            </div>
            <div property="rnews:description">Rebel fighters take...</div>
             
            <!-- Adding hidden triples to our image object. -->
            <div style="display:none">
              <div property="rnews:mediaType">Picture</div>
              <div rel="rnews:mediaTypeUri"
               href="http://cv.iptc.org/newscodes/mediatype/picture" >
              </div>
            </div>
            </div>
          </div>
          <div rel="rnews:createdBy">
            <div about="http://topics.nytimes.com/topics/reference/timestopics/people/m/steven_lee_myers/"
             typeof="rnews:person">By 
            <span property="rnews:name">STEVEN LEE MYERS</span>
            </div>
          </div>
          <div>
            <span property="rnews:dateline">WASHINGTON</span> | 
            <span property="rnews:dateCreated" content="2011-03-24">March 24, 2011</span>
          </div>
          <div property="rnews:body">
            <p>Having largely succeeded...</p>
          </div>
          <div>
            <p>
            <a href="http://www.nytimes.com/content/help/rights/copyright/copyright-notice.html"
               rel="rnews:copyrightNoticeUri">
              © Copyright 2011
            </a>
            <span>The New York Times Company</span>
            </p>
            <p>
            <a href="http://www.nytimes.com/ref/membercenter/help/agree.html"
               rel="rnews:usageTermsUri">
              Disclaimer
            </a>
            </p>
          </div>
          </div>
          <div>
          <div>
            <div>Section</div>
            <div property="rnews:section">World</div>
          </div>
          <div>Tags</div>
          <div>
            <div rel="rnews:taggedBy">
            <div>People</div>
            <div about="http://data.nytimes.com/91178019641520997503" typeof="rnews:Person">
              <span property="rnews:name">Qaddafi, Muammar el-</span>
            </div>
            </div>
          </div>      
          <div rel="rnews:discussedBy">
            <div>Discussion</div>
            <div about="http://community.nytimes.com/comments/www.nytimes.com/2011/03/25/world/africa/25policy.html?permid=4#comment4" typeof="rnews:comment">
            <div property="rnews:commentText">So the question is...</div>
            <div rel="rnews:createdBy">
              <span about="http://timespeople.nytimes.com/view/user/27242827" typeof="rnews:person">
              <a href="http://timespeople.nytimes.com/view/user/27242827"
                 property="rnews:name">Chuck</a>
              </span>
            </div>
            <div property="rnews:commentTime" content="2001-03-25T08:27:00">March 25th, 2011 8:27 am</div>
            </div>
          </div>
          </div>
        </div>
        <div style="display:none">
          <div property="rnews:description">The questions about the...</div>
          <div property="rnews:language">en</div>
          <div rel="rnews:thumbnailUri"
           href="http://http://graphics8.nytimes.com/images/common/icons/t_wb_75.gif"></div>
          <div rel="rnews:copyrightedBy rnews:hasSource rnews:providedBy">
          <div about="http://www.nytimes.com" typeof="rnews:Organization">
            <div rel="rnews:tickerSymbol">
              NYSE NYT
            </div>
          </div>
          </div>
        </div>
        </body>
        </html>

See this HTML code as stand-alone web page - don't expect any fancy layout, just use it as source for experimenting with rNews RDFa embedded into HTML.

In Conclusion

So that's it! All you need to embed rNews markup into your HTML news documents. Now go forth and embed.