Entity Notation (NN) | The Universe Web

Duncan Cragg

NN is primarily about inter-Entity links that build a Web of Entities. NN also adds a notation for ordered hashes.

Entity Notation (NN) applies only to the "content": part of the Entity, not the "headers": part. All NN JSON extensions are flagged by having hyphens either side. NN is fully-compliant JSON, extended in these ways:

Intra-JSON links

Adding 'invisible' local name to lists and hashes:

   { "-id-": "-14-", "tag": "value" } == -14-{ "tag": "value" }
   [ "-id-:-14-",           "value" ] == -14-[        "value" ]
   [ "-id-", "-14-",        "value" ] == -14-[        "value" ]

Using it:

   "a": { "-id-":"-14-", "b": "c" }
   "d": { "e": "-14-" }

Now "d" looks like:

   "d": { "e": { "b": "c" } }

Inter-JSON links

   UID:   "sub-json": "-123-456-789-"
   URL:   "sub-json": "-http://host/path/u/123-456-789.js-"

This is semantically equivalent to transparently including the sub-JSON "content": in place of the link. URLs are distinguished from UIDs/ids by having any slash.

A whole JSON structure with a uid can have an optional =-uid-= in a similar way to =-id-=:

{ "-uid-":"-1d7-a14-", "tag": "value" } == -1d7-a14-{ "tag": "value" }

The following are all equivalent as far as NN is concerned (this shows how individual Entities and their header/content pair are effectively invisible to the NN graph; content parts are sewn together):

   { "headers": { "UID":  "9a1c3340-fe3328" },
     "content": { "x": "-13cea-0aa281-" }
   }

   { "headers": { "UID": "13cea-0aa281" },
     "content": { "a", "b" }
   }

   ==

   { "headers": { "UID":  "9a1c3340-fe3328" },
     "content": { "x": { "headers": { "UID": "13cea-0aa281" },
                         "content": { "a", "b" }
                       }
             }
   }

   ==

   { "headers": { "UID":  "9a1c3340-fe3328" },
     "content": { "x": { "-uid-":"-13cea-0aa281-", "a", "b" } }
   }

   ==

   { "headers": { "UID":  "9a1c3340-fe3328" },
     "content": { "x": { "-id-":"-1-", "a", "b" } }
   }

   ==

   { "headers": { "UID":  "9a1c3340-fe3328" },
     "content": { "x": { "a", "b" } }
   }

   ==

   { "x": { "a", "b" } }

Merging JSON Objects and Lists

If a sub-JSON needs to be transparently included 'higher up', use "-etc-":

   "a": 1,
   "b": 2,
   "-etc-": "-123-456-"

if 123-456 is:

   "b": 3,
   "c": 4

results in:

   "a": 1
   "b": 3,
   "c": 4

.. the 'up'ed JSON overwrites any pre-existing elements.

Again, "-etc-" links are to "content": parts. Merging a non-hash into a hash is meaningless.

Lists can also be up'd:

111-111-111:

   [ "-123-321-", "-4114-414-", "-4577-242-" , "-772-4542-" ]

Can be split like this:

111-111-111:

   [ "-123-321-", "-4114-414-", "-etc-:-111-111-222-" ]

111-111-222:

   [ "-4577-242-" , "-772-4542-" ]

If a list is needed explicitly, put it immediately after the '-etc-' string:

   [ "-123-321-", "-4114-414-", "-etc-", [ "-4577-242-" , "-772-4542-" ] ]

Now sub-lists can be 'pulled out' and referred to locally inside the structure:

  "a": [ "-123-321-", "-4114-414-", "-etc-", [ "-id-:-x-", "-4577-242-" , "-772-4542-" ] ],
  "b": "-x-"

Looks like:

  "a": [ "-123-321-", "-4114-414-", "-4577-242-" , "-772-4542-" ]
  "b": [ "-4577-242-" , "-772-4542-" ]

Merging a non-list into a list is meaningless, unless it's an ordered hash/object, when the tags are dropped, and only the values inserted.

Ordered Hash/Object

{ "-order-": ["do", "ray", "me"],
  "me": "last thing",
  "ray": "middle thing",
  "do": "first thing"
}

Java supports ordered hashes in the LinkedHashMap class.

Order can be calculated by sorting the tags/keys:

  { "-order-": "sort",  "0": "a",  "1": "b",  "2": "c" }
  similar to: [ "a", "b", "c" ]

Duncan Cragg, July 2008

_[2278]