Skip to content

Item link relation type

Scott Smith edited this page Jun 18, 2013 · 6 revisions

Item links point to documents which are building blocks of the current document.

If the current document is a news story or a blog post, then item links would point to various assets (images, video, audio etc.) that are part of the news story/the blog post.

In the case when the current document is a list of blog posts, the item links would point to each individual blog post.

The links in item link relation is the way for a Collection.doc+JSON document to communicate its ordered structure. Ordering is meaningful.

It is important to understand the difference between this relation and that of collection link[./Collection-Link-Relation-Type]. The difference is both in direction of linkage, as well as authority: item allows document to specify its structural parts, whereas collection allows any other document to say that they consider themselves to be in "part of" relationship with document X. Associations indicated through the collection link relationship are unordered.

For example, Collection.doc+JSON news story document may represent its assets as:

{
  "version" : "1.0"
, "data" : {  
    "guid"        : "f84e9018-5c21-4b32-93e8-c519308620f0"
  , "title"       : "Breaking News"
  , "published"   : "2013-02-11T13:21:31.598Z"
  , "byline"      : "By: Bryan Naylor & Christopher Joyce"
  , "description" : "<p>lorem ipsum 1<p><img src=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;http://media.npr.org/someiage.pngfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;><p>lorem ipsum 2<p>lorem ipsum 3<p><audio autoplay=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;autoplayfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot; controls=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;controlsfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;><source src=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;http://media.npr.org/somesegment.oggfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;><source src=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;http://media.npr.org/somesegment.mp3fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;></audio>"
  , "hreflang"    : "en" 
  , "contentencoded": "<p>lorem ipsum 1<p><img src=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;http://media.npr.org/someiage.pngfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;><p>lorem ipsum 2<p>lorem ipsum 3<p><audio autoplay=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;autoplayfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot; controls=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;controlsfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;><source src=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;http://media.npr.org/somesegment.oggfbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot; ><source src=fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;http://media.npr.org/somesegment.mp3fbd334d2913e527f3ea413afa0a7c85e3d2b6c77quot;></audio>"
  , "contenttemplated": "lorem ipsum 1 \n {{#c7d6cd84-6b28-4ea2-ae82-a7435bea6679}} \n lorem ipsum 2 \n lorem ipsum 3 \n {{#c34c2dca-fafb-43c8-ac9c-109dc3516630}}"
  }   
, "links" : {
    "profile"      : [ { "href" : "http://api.pmp.io/profiles/story"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "self"         : [ { "href" : "http://api.pmp.io/docs/f84e9018-5c21-4b32-93e8-c519308620f0"}]
  , "item"         : [ { "href" : "http://api.pmp.io/docs/c7d6cd84-6b28-4ea2-ae82-a7435bea6679"}
                     , { "href" : "http://api.pmp.io/docs/c34c2dca-fafb-43c8-ac9c-109dc3516630"}
  , "queries"      : [ {"href" : "http://api.pmp.io/docs/queries",   "type": "application/vnd.pmp.query+json"}]
  , "edit-form"    : [ {"href" : "http://api.pmp.io/docs-validator", "type" :   "application/json"}]
  }  
, "items" : [ 
    { "version" : "1.0"
    , "data" : {
        "title" : "Some Image"
      , "guid" : "c7d6cd84-6b28-4ea2-ae82-a7435bea6679"
      , "type" : "image"
      , "published" : "2013-02-11T13:21:31.598Z"
      }
    , "links" : {
                "profile"      : [ { "href" : "http://api.pmp.io/profiles/media"
                                   , "type" : "application/vnd.pmp.collection.doc+json" }]
              , "self"         : [ {"href" : "http://api.pmp.io/docs/c7d6cd84-6b28-4ea2-ae82-a7435bea6679"}]
              , "distributor"  : [ {"href" : "http://api.pmp.io/docs/d99273a21-10ac-43d3-83c5-5333b0259e17", "title": "Getty"}]
              , "enclosure"    : [ {"href" : "http://media.npr.org/someiage2.png", "type" : "image/png"}]
              }
    }  

  , { "version" : "1.0"
    , "data" : {
        "title" : "Some Audio"
      , "guid" : "c34c2dca-fafb-43c8-ac9c-109dc3516630"
      , "type" : "audio"
      , "published" : "2013-02-11T13:21:31.598Z"
      }
    , "links" : {
                "profile"      : [ { "href" : "http://api.pmp.io/profiles/media"
                                   , "type" : "application/vnd.pmp.collection.doc+json" }]
              , "schema"       : [ {"href" : "http://api.pmp.io/schemas/audio",  "type" : "application/schema+json"}]
              , "self"         : [ {"href" : "http://api.pmp.io/docs/c34c2dca-fafb-43c8-ac9c-109dc3516630"}]
              , "distributor"  : [ {"href" : "http://api.pmp.io/docs/95813612-4143-4116-a335-3f26fa0eee34", "title": "Sony"}]
              , "enclosure"    : [ {"href" : "http://media.npr.org/someaudio.mp3", "type" : "audio/mp3"]
              }
    } 
  ]
, "error" : {OBJECT}
}

Items Array

Please notice that the top-level items array is provided on output and is a dereferenced representation of the item links. This is done for convenience of the API clients to remove the need of them making numerous HTTP requests for fetching the items. The items array, however, is a read-only, convenience property and the authoritative representation of the items is still the array of item links. API clients CANNOT use items array during publishing. They need to link to existing documents using item links instead.

Something went wrong with that request. Please try again.