Examples

Note: this is not  quite correct against the latest syntax: to be revised)

Example 1: XML Purchase Order

These examples use the well-known XML “Purchase Order” example.

No change from the XML is needed. The XML Header is read just as an Implementation Parameter.

The RAN parser will treat the top-level element as the start of a branch.

<?xml version="1.0"?>
<purchaseOrder orderDate="1999-10-20">
    <shipTo country="US">
        <name>Alice Smith</name>
        <street>123 Maple Street</street>
        <city>Mill Valley</city>
        <state>CA</state>
        <zip>90952</zip>
    </shipTo>
    <billTo country="US">
        <name>Robert Smith</name>
        <street>8 Oak Avenue</street>
        <city>Old Town</city>
        <state>PA</state>
        <zip>95819</zip>
    </billTo>
    <comment>Hurry, my lawn is going wild!</comment>
    <items>
        <item partNum==="872-AA">
            <productName>Lawnmower</productName>
            <quantity>1</quantity>
            <price>148.95</price>
            <comment>Confirm this is electric</comment>
        </item>
        <item partNum==="926-AA">
            <productName>Baby Monitor</productName>
            <quantity>1</quantity>
            <price>39.98</price>
            <shipDate>1999-05-21</shipDate>
        </item>
    </items>
</purchaseOrder>

Example 2: RAN converted from XML Purchase Order with Namespaces and Datatyping

The change to represent the namespace URI using link is trivial. Some attributes have datatyped values. If multiple fragments were sent, we can refer to the first Item as 999503:872-AA for keyed access. Some of element  end-tags  use short-tags.  (The prefixes on the attribute names are just because that is what the MS version has.)

<:aw xmlns="http://www.eg.com/ran/ns" :>

<<<aw:PurchaseOrder
    aw:PurchaseOrderNumber===99503
    aw:OrderDate=1999-10-20 >>>
  <aw:Address aw:Type==Shipping>
    <aw:Name>Ellen Adams</aw:Name>
    <aw:Street>123 Maple Street</aw:Street>
    <aw:City>Mill Valley</aw:City>
    <aw:State>CA</aw:State>
    <aw:Zip>10999</aw:Zip>
    <aw:Country>USA</aw:Country>
  </aw:Address>
  <aw:Address aw:Type==Billing>
    <aw:Name>Tai Yee</>
    <aw:Street>8 Oak Avenue</>
    <aw:City>Old Town</>
    <aw:State>PA</>
    <aw:Zip>95819</>
    <aw:Country>USA</>
  </aw:Address>
  <aw:DeliveryNotes>Please leave packages in shed by driveway.</aw:DeliveryNotes>
  <aw:Items>
    <aw:Item aw:PartNumber==="872-AA">
      <aw:ProductName>Lawnmower</>
      <aw:Quantity>1</>
      <aw:USPrice>148.95</>
      <aw:Comment>Confirm this is electric</>
    </aw:Item>
    <aw:Item aw:PartNumber==="926-AA">
      <aw:ProductName>Baby Monitor</>
      <aw:Quantity>2</>
      <aw:USPrice>39.98</>
      <aw:ShipDate>1999-05-21</>
    </aw:Item>
  </aw:Items>
<<</aw:PurchaseOrder aw:PurchaseOrderNumber===99503>>>

Example 3: Stream of Fragments

This example has three fragments, marked up as if an infinite stream (i.e., no highest-level wrapper tags.) The fragment id of each will be taken from the first attribute.  The  :=  marks-up an ID attribute.

<<<purchaseOrder 
     orderNumber===99503
     orderDate=1999-10-20>>>
    <shipTo country=US>
        <name>Alice Smith</>
        <street>123 Maple Street</>
        <city>Mill Valley</>
        <state>CA</>
        <zip>90952</>
    </shipTo>
    <billTo country=US>
        <name>Robert Smith</>
        <street>8 Oak Avenue</>
        <city>Old Town</>
        <state>PA</>
        <zip>95819</>
    </billTo> 
<<</purchaseOrder   orderNumber===99503>>>

<<<purchaseOrder 
     orderNumber===99504
     orderDate=1999-10-20>>>
   <shipTo country=JP>
        <name>山本蓮</> 
        <丁目 番号>3-5-10</>
        <町>O-yama</&#x753A;>  <-- The end-tag uses a character reference -->
        <区>Itabashi</区>
        <都>Tokyo</都>
    </shipTo>
    <billTo country=US>
        <name>Robert Smith</>
        <street>8 Oak Avenue</>
        <city>Old Town</>
        <state>PA</>
        <zip>95819</>
    </billTo> 
</purchaseOrder  orderNumber===9504>>>

<<<purchaseOrder 
     orderNumber===99505
     orderDate=1999-10-20>>
    <shipTo country=AU>
        <name>Fricko Eurorack Modules</>
        <street>123 Kanagaattack Street</>
        <city>Russell Lea</>
        <state>NSW</>
        <zip>2046</>
    </shipTo>
    <billTo country=US>
        <name>Robert Smith</>
        <street>8 Oak Avenue</>
        <city>Old Town</>
        <state>PA</>
        <zip>95819</>
    </billTo> 
<<</purchaseOrder orderNumber===99505>>>

 

Example 4: Long names, character references everywhere

Here is an example, which has IPs and Comment with character references, links attached to the document, names that are strings, and a second fragment which is an element with a link to the “Shipping details” element in the first. The date of the Order Raised has T%09 which is ISO8601-ese for approximately 9 a.m.

<?po deliver-through="sleet &amp; snow" ?> 
<?links css ="http://www.eg.com/ran/po.css"
      xsd ="http://www.eg.com/ran/po.xsd"
      schematron ="http://www.eg.com/ran/po.sch"
      javascript ="http://www.eg.com/ran/po.js" ?>
<<<"Fricko Purchase Order"  orderId===A12345 "Order Raised"=1999-10-20T%09 >>>
 <-- is "sleet &amp; snow" too corny? -->
 <"Shipping details" country===US>
  <name>Alice Smith</name>
  <po:street>123 Maple Street</street>
  <po:city>Mill Valley</city>
  <po:state>CA</state>
  <po:zip>90952</zip>
 </"Shipping details">
<<</"Fricko Purchase Order" orderId===A12345>>>
<<<summary id===s1  "link to shipping details" =} A12345+US >>>
<<</summary id===s1 >>>

Example 5: Empty Names and Anonymous Element Tags

This example has anonymous elements, to provide list or arrays, with some simple typed values. Inside the list it uses short end-tags.

<<<""
 id==="example1"
 firstName== "John"
 lastName == "Smith”
 isAlive" = true
 age = 27
>>>
 <address streetAddress = "21 2nd Street"
      city = "New York" state = "NY" postalCode = "10021-3100" >
     <phoneNumbers>
     <_>
         <home number = "212 555-1234" ></>
         <office type = "office" number = "646 555-4567" ></>
     </_>
   </phoneNumbers>
  </address>
  <children><_></_></children>
  <spouse></spouse>
<<</"" id=specific=="example1">>>

This is version of JSON1 example on the Wikipedia entry2, with the following mappings:

  • JSON Objects converted to RAN elements with empty names

  • JSON Arrays converted to RAN anonymous element tags i.e. <_> and </_>

  • JSON keys converted to lexical names (though they could be kept as strings)

  • JSON values kept as RAN strings, numbers or boolean. A value that is an object or array converted to a named element.

  • An empty RAN anonymous element takes for its name the value of a JSON field “type”.

  • JSON null has no exact equivalent here, and so is just an empty element.

The JSON original example uses 40 characters of delimiters (excluding quotes). The RAN example above uses 66. (This difference is essentially the price of the explicit end-tags.)

Example 6: Random/indexed access to fragments based on metadata query

Note: this is not  quite correct against the latest syntax: to be revised)

The developer wants to have very large RAN documents with large numbers of small-ish fragments with both fields and mixed content, for a Big Data AI system, Astoundo. They want to have random access to fragments based on fragment metadata, using Implementation Parameter  of their own development. They generate RAN documents as follows:

1. Each fragment start-tag contains the metadata required as attribute values.

2. As the document is generated, the fragment-start-tags are stored.

3. At the end of the document, IPs are  created containing Implementation Parameters with the same information as the fragment start-tag: this can just be a simple text copy operation on the raw text, it is not necessary to parse or tokenize the attributes and values. The IPs have either the index of the start-tag or the byte position in the file of the fragment-start delimiter.

4. The whole thing is wrapped using finite stream  tags (with four <) so we know when the end is.

<<<<data>>>>

…
<<<intel  id===A123
           date=2021-08-10
           informantReliability=A
           informantCertainty=B
            incident=}Z1233>>>
…
<<</intelid ===A123 >>>
   …
 
<?fragment-index position=10element=intelid=}B100
        date=2019-04-14informantReliability=E informantCertainty=E
           incident=Z1233?>
    …

<?fragment-index position=123456 element=intelid=}A123
        date=2021-08-10 informantReliability=AinformantCertainty=B
        incident=Z1233?>

<<<</data >>>>

So to use these, the reader system:

1. When the document is accessed, it can be parsed from the back backwards to find the Pis.

2. It then uses the attributes to find fragments of interest, and then to either go directly to the correct position, or to scan forwards from the start to the fragment with that index, or (if it thinks the position or index are not reliable) to match the fragment on the name, fragment id (the first attribute value) and the other attribute values.

3. (If it locates other anonymous elements with these IPs in the document, they should be ignored or replaced with spaces, as the are superseded leftovers from previous indexing operations, and more fragments have subsequently been appended.)

Note: XML could also be made which appends IPs with absolute positions of elements or indexed positions of child elements. However, the indexed elements cannot be scanned for fast: you need to scan all the element tags to find the ones of interest. And you cannot simply append more fragments to the end. And with XML you would need extra conventions, i.e. that you are only looking at /*/* and which ones you are interested in as being the equivalent of fragments.

However: If we consider a further case, where this indexing is a separate process to the document generation, for example a pipeline process, then an advantage with XML becomes clearer: the indexer only needs to scan for <<<[^/] and save the text until the next >>> with its position (or count). It does not need to parse the XML (or even lex all tags) in order to generate this index.

1Implemention Note: This mapping is indicative, and not a part of RAN, nor is it a warrant that JSON and RAN are 100% mutually interconvertable, nor that RAN is intended for the uses that JSON is suited too.

2https://en.wikipedia.org/wiki/JSON#Syntax as at 2021-07-31

Example 7: Attributes with Multiple Tuples of Binary

<data binary= 
   [ 0x0000 0x019F 0x1230 ]
   [ 0x0000 0x019F 0x1230 ]
   [ 0x1000 0x019F 0x1230 ]  
></data>

An attribute value can be one or more tuples using “[” and "]").  Each tuple should be the same length. Each tuple may contain any kind of token, but each tuple should have the same type in corresponding positions.  Currently, a tuple may not contain a tuple.