What would a better JSON look like?

document_navigation.md

Referencing Values within HRON Documents

HRON-Path is a standard for accessing values within HRON documents.

("urn:isbn:978-1891024634") {
  title: "Andy Warhol Prints: A Catalogue Raisonné 1962-1987",
  edition: "4th Revised, Expanded Edition (April 2, 2003)",
  publisher: <href: "https://www.wikidata.org/wiki/Q5283109",
    type: "https://schema.org/Organization">,
  dimensions: "9.8 x 1.5 x 11.8 inches",
  weight: "5.4 pounds",
  authors: [
    <href: "https://www.wikidata.org/wiki/Q365129", 
      type: "https://schema.org/Person", value: "Jörg Schellmann">,
    <href: "https://www.wikidata.org/wiki/Q18386358",
      type: "https://schema.org/Person", value: "Arthur Danto">,
    <href: "urn:person:Donna deSalvo">,
    <href: "urn:person:Claudia Defendi">,
    ("https://www.wikidata.org/wiki/Q5603", type: "https://schema.org/Person") {
      name: "Andy Warhol"
    }
  ]
}

Loading the document with the JavaScript statement var book = Heron.load(doc) results in an object that may be queried with a path language.

book('title')                  // "Andy Warhol Prints: A Catalogue Raisonné 1962-1987"

Note that a hyperlink with a value parameter can evaluate to the specified value. If a HRON path requests a property that is unknown for the hyperlink value, a network lookup is triggered, returning a promise object.

book('author[0]')              // "Jörg Schellmann"
book('author[0][birth_date]')  // <href: "https://www.wikidata.org/wiki/Q365129">

Array path operations:

Operator	Description
*	Wildcard; selects all elements of an array
<int>	Array offset; can be negative for reverse indexing
<int>(,<int>)*	Array index list; selects each of the indexed items in order
<int>:<int>	Array slice operator

Object path operators:

Operator	Description
..	Deep search; scans each property of an object

Examples:

Selector	Explanation
books('*[authors[..][name]="Liam Gillick"]')	Returns the list of books whose author name equals "Liam Gillick"
books('*[title,authors]')	Returns a list of objects containing only the title and authors properties from each book
books('authors[..]<*>')	Returns a list of objects ...
books('<type="https://schema.org/Person">')	Returns a list of all hyperlinks that have the type specified by the semantic schema at https://schema.org/Person

object_notation.md

Hypermedia Relational Object Notation

Hypermedia Relational Object Notation (or HRON, and pronounced "heron") is a data-interchange format for hypermedia applications. HRON is a text format that is language-agnostic but uses convetions familar to many programmers.

HRON has two top-level structures:

• An associative array of name-value pairs
• An ordered list of values

In addition to the familiar values from similar formats, HRON introduces two new literals that are useful in hypermedia documents. The hyperlink literal is a list of key-value pairs delimited by angle brackets. Additionally, any value may be prefixed with a URI literal which is enclosed in parentheses.

A link literal represents a reference to a value stored in another location. The location may be elsewhere in the current document or in a well-specified location on a remote host. Link literals are delimited by angle brackets (< and >). Link literals must contain an href parameter that is a valid URI, and may contain rel, type, lang, and methods parameters.

<href: "urn:isbn:978-1891024634", rel: "publication">

A URI literal is simply a parenthesized string literal.

("http://scrapi.org/object/482835")
("tel:+1-212-570-3600")

A URI literal is an optional annotation for a value and may not be used as a stand-alone value.

{
  user: ("urn:uuid:6869acb6-1a8b-44c7-a5c1-978d2e171af7") {
    name: "Brendan Berg",
    email: "brendan@example.org",
    last_login: "2016-08-10"
  }
}

Below is a lengthier example showing URI annotationss and hyperlink values in use. Note that in this case, the URIs in the hyperlink values correspond to the URIs in the annotations, but this is not a requirement. If a hyperlink cannot be followed in the current document, the resource may be fetched from a remote source.

{
  artist: ("openart.org/artist/6246") {
    name: "Andy Warhol",
    born: "1928-08-06",
    died: "1987-02-22",
    works: [
      <href: "openart.org/work/316.1962">,
      <href: "openart.org/work/2480.2001">,
      ...
      <href: "openart.org/work/7531">
    ]
  },
  works: [
    ("openart.org/work/316.1962") {
      title: "Gold Marilyn Monroe",
      artist: <href: "openart.org/artist/6246", display: "Andy Warhol">,
      year: "1962",
      medium: "Silkscreen ink on synthetic polymer paint on canvas"
      dimensions: "H 6'11 1/4\" W 57\"",
      credit: "Gift of Philip Johnson",
      object_number: "316.1962",
      copyright: "© 2016 Andy Warhol Foundation for the Visual Arts / Artists Rights Society (ARS), New York",
      department: <href: "openart.org/department/painting-and-sculpture", display: "Painting and Sculpture">
    },
    ("openart.org/work/2480.2001") {
      title: "Double Elvis",
      artist: <href: "openart.org/artist/6246", display: "Andy Warhol">,
      year: "1963",
      medium: "Silkscreen ink on synthetic polymer paint on canvas"
      dimensions: "H 6'11 1/4\" W 53\"",
      credit: "Gift of the Jerry and Emily Spiegel Family Foundation in honor of Kirk Varnedoe",
      object_number: "2480.2001",
      copyright: "© 2016 Andy Warhol Foundation for the Visual Arts / Artists Rights Society (ARS), New York",
      department: <href: "openart.org/department/painting-and-sculpture", display: "Painting and Sculpture">
    },
    ("openart.org/work/7531") {
      title: "Empire",
      artist: <href: "openart.org/artist/6246", display: "Andy Warhol">,
      year: "1964",
      medium: "16mm film (black and white, silent)",
      duration: "8 hrs., 5 min. at 16 frames per second",
      credit: "Original film elements preserved by The Museum of Modern Art, New York. Gift of The Andy Warhol Foundation for the Visual Arts, Inc.",
      object_number: "7531",
      copyright: "© 2016 Andy Warhol Foundation for the Visual Arts / Artists Rights Society (ARS), New York",
      department: <href: "openart.org/department/film", display: "Film">
    }
  ]
}