Graph Structures and Links

Identifiers and References

RAN gives a lexical  means of representing graph structures in a document without requiring a schema.  A RAN document is therefore a sequence of trees overlaid with directed links between and inside them. One-to-one, one-to-many, many-to-one and many-to-many links are supported. An element may have multiple links. 

A user should reasonably expect that anchors are indexed, that some kind of caching of links is performed, and that multi-factor matching against names in anchors is supported.  Similarly, they should reasonably expect that attributes that are not anchors or targets do not have any special indexing. 

Identifiers

Anidentifier is a special kind of attribute that identifies an element, for linking. 

• The special delimiter := is used
• The attribute value may be
  
• a literal or name, which are treated equivalently
• a tuple of names and literals, in which case they all identify the element.

The identifier on a fragment start-tag is called the fragment key.  It must appear as the first attribute.  (More than one attribute may name identifiers or references.)

References

A link is a special kind of attribute that identifies one or more reference elements

• The special delimiter  =:  is used for a normal forward link
• The attribute value must be
• a literal, in which case it is the id of element(s) in the current fragment
• an reference-path, which identifies the fragment key and perhaps other ancestor references
• a URI,
• a relative path (to a file in the file system)
• a tuple of literals and or reference-paths, in which case the link is to or from all the specified elements.
• The link can be named using the attribute name.

Because reference-paths are used, the link may be a 1:many link, and may have wildcards.

Example

 First we have a fragment x with various anchors specified.

<<<x id:="f1">  <a> <b me:=b23>  <c ima="c34"  /> </b></a>   </x id:="f1">>>

Next we have a fragment y which has a link with an reference-path to identify the reference.

<<<y ... >   <look   overthere=:f1+b23+c34  />   </y ...>>>

Reference Paths

Reference Paths are a new concept. They are like a simple XPath on the identifier names of the current RAN stream, but made with identifier values not element names.

• An reference-path is a typed value  (i.e. not in double quotes) that contains "+" or "~" not as the first character. 
• A path of x+y+z  means "the element with an identifier of 'z' , which is any descendant of the element whose identifier is 'y', which is an descendant of the fragment whose identifier is 'x'. 
• + selects the lexically first path. If there are multiple matches, only the first is used.
• + establishes a 1:1 relation, or link. The name of the relation is the attribute name.
• A path of x~y~z  means "all elements with an identifier of 'z' , which are  descendant of alls element whose identifier is 'y', which are descendants of the fragment whose identifier is 'x'. 
• ~ establishes a relation to all. If there are multiple matches, only the first is used.
• ~ establishes a 1:many relation. The name of the relation is the attribute name.
• * can be used as a wildcard
• * in the first position means "all fragments"
• * in the last position means "all elements with any identifier" (descendant of the preceding path)
• Identifiers are referenced as tokens.
• If the identifier was a string literal containing a single token only, that is taken as a token. This is the only instance in RAN where the distinction between tokens and literals are blurred, and is discouraged.  If the identifier was a string literal containing multiple tokens, the first token may be used, and a warning may be issued.
• There is no way to address a <[>  </]>  element, as these cannot have attributes and therefor IDs. However, the parent element can give a content identifier using ==: which may effectively do the same.

Example

If I have two element types Woman and Man, in a Fragment with fragment key "Royals"  then the following are equivalent links  (assuming the identifiers are unique ids):

<Woman id:=Elizabeth_II child =:[Charles_III Ann Andrew Edward ]>...</Woman>
<Man   id:="Charles_III">...</Man>
<Woman id:=Ann>...</Woman>
<Man   id:=Andrew>...</Man>
<Man   id:=Edward>...</Man>

and with links from the children back to the parent

<Woman id:="Elizabeth_II" child =:[Charles_III Ann Andrew Edward ]>...</Woman>
<Man   id:=Charles_III parent =:"Elizabeth_II" >...</Man>
<Woman id:=Ann         parent =:"Elizabeth_II" >...</Woman>
<Man   id:=Andrew      parent =:Elizabeth_II >...</Man>
<Man   id:=Edward      parent =:Elizabeth_II >...</Man>

and

<<<Family who:=Royals decade=195X >>>
  <Woman id:=Elizabeth_II    child =:[Charles_III Ann]>...</Woman>
  <Man   id:=Charles_III >...<Man>
  <Woman id:=Ann     >...<Woman>
<<</Family>>>

<<<Family who:=MoreRoyals decade=196X >>>
  <Man   id:=Andrew    parent =:Royals+Elizabeth_II >...<Man>
  <Man   id:=Edward    parent =:Royals+Elizabeth_II >...<Man> 
<<</Family>>>

To explain this last example:  we have a fragment for a Family (dated to the 1950s with an ISO 8601 wildcard) where Elizabeth_II has child links to Charles and Ann.  Then we append another fragment (dated to the 1960s with a wildcard)  for Andrew and Edward: these link to Elizabeth_II.

It is a dynamic reportable error if a link dangles.

Links

Link tags can appear in a document preamble.  They allow definition of properties for a prefix, goes immediately after the open delimiters "<:".  Any element tag name or fragment tag name that has a prefix is implicitly linked to the properties of the matched link tag. 

There are two special prefixes that can be declared in link tags:

•  "/" for the whole document (note quotes)

• "" for any anonymous element with no  name

All attributes inside the link tag are properties of that document or element with a name with matching prefix.¹⁸

Footnotes

18Implementation Note: Represent XML namespaces using an attribute xmlns in a link tag. Represent links to schemas, code objects, stylesheets, using links. Put version and tracing metadata in a link tag. Metadata such as MIME metadata or Dublin Core may be exposed as a link tag. It can be used to transmit default values. (It might be good for RAN to specify most of these uses, adopting HTML-ish names where possible.)