This page is referenced by:

• 1 2014-10-01T16:38:34-07:00 Reading Content from the API 30 Understanding the RDF syntax used in Scalar's API plain 2019-02-07T20:12:04-08:00

  All API results are returned in RDF, serialized as either RDF-XML or RDF-JSON. The serialization can be managed by the ?format=[xml|json] GET variable (xml is the default). RDF can be intimidating when first encountered. However, it can be summed up by stating that it is content presented in a flattened or non-hierarchical way. For example, each Scalar node — page, media, annotation, etc. — is a node in the RDF output. Additionally, each relationship is also a node, linking two other nodes together. The relationship nodes are at the same hierarchical level as the content nodes, thus presenting RDF’s flattened hierarchy.

  Content Nodes

  As a practical example, consider the home page of this User's Guide represented in RDF-XML:

  In the above example, you can see that a piece of Scalar content is broken into two RDF nodes: first, the content wrapper, and then its version. In this case, the version number 23 of the piece of content is output. Here's a schematic of the RDF above:

  
  [start
      [“Welcome” page content wrapper]
      [“Welcome” page version 23]
  end]
  
  

  Note that the URL in the rdf:Description element includes the version number “.23” at its end—this points to a specific version of the content, which is usually not what you want when working with API data. Instead, use the URL in the content wrapper’s rdf:Description element, which will always point to the most recent version.

   

  Relationship Nodes

  Now consider a second piece of content with the URL, http://scalar.usc.edu/works/guide/getting-started. To create a relationship between the two pieces of content, a third node can be provided in RDF when the recursion level of the RDF is greater than zero (e.g., using the ?rec=1 GET variable) stating that the output is recursing relationships to the first degree.  In the example below, you can find the first relationship node by looking for "<rdf:Description rdf:about="urn:scalar:path:210521:36977">":

   

  Here’s a schematic of the RDF above:

  
  [start
      [“Getting Started” page content wrapper]
      [“Getting Started” page version 4]
      [“Getting Started” is the 1st child of “Welcome”]
      [“Welcome” page content wrapper]
  ​​​    [“Welcome” page version 23]
      [“Creating an Account” is the 1st child of “Getting Started”]
      [“Creating an Account” page content wrapper]
      [“Creating an Account” page version 11]
      [“Creating Your First Book” is the 2nd child of “Getting Started”]
      [“Creating Your First Book” page content wrapper]
      [“Creating Your First Book” page version 5]
      [“Getting to Know the Interface” is the 3rd child of “Getting Started”]
      [“Getting to Know the Interface” page content wrapper]
      [“Getting to Know the Interface” page version 8]
      [“Reading in Scalar” is the 4th child of “Getting Started”]
      [“Reading in Scalar” page content wrapper]
      [“Reading in Scalar” page version 6]
      [“Further Explorations” is the 5th child of “Getting Started”]
      [“Further Explorations” page content wrapper]
  ​​​​​​​    [“Further Explorations” page version 3]
  end]
  
  

  In the first relationship node, a body (oac:hasBody) is described as the home page (/index), and the target (oac:hasTarget) as the getting started page (/getting-started). The hash fragment (the string after the # character) of the target describes the type of relationship, in this case “Getting Started” is index 1 of the home page. Put another way, the home page is a path containing other pages where “Getting Started” is the first page in the path. If no hash fragment is present on the target then the relationship is a Tag. Other relationships types will have different hash fragments.

   

  RDF-JSON

  RDF-XML can be difficult to parse (for example, in JavaScript and PHP), therefore the Scalar API also offers the same data in the RDF-JSON format. Here is similar content to that described above outputted in JSON format (using the ?format=json GET variable):

  In RDF-JSON, data is provided as an object. The only difference between an RDF-JSON object and a typical JSON object is that rather than index numbers to denote each node as in JSON (e.g., 0, 1, 2, …), in RDF-JSON the URL of each node acts as its key.

  Sample Code

  Pages and Versions can be easily placed into lists by looking at each node’s “rdf:type” which will be one of Composite (i.e. Page), Media, or Version.

  var pages = [], versions = [];
  for (uri in json) {
    var type = json[uri][‘http://www.w3.org/1999/02/22-rdf-syntax-ns#type’];
    if (-1!=type.indexOf(‘Composite’)||-1!=type.indexOf(‘Media)) pages.push(json[uri]);
    if (-1 != type.indexOf(‘Version’)) versions.push(json[uri]);
  }