Product SiteDocumentation Site

6.7. jn:encode-for-roundtrip

This function recursively encodes non-JSON types in such a way that they can be serialized as JSON while keeping roundtrip capability.
The following computations are made with respect to the static context of the caller, so that the schema type definitions are available.
jn:encode-for-roundtrip($items as item()*) as item()*
jn:encode-for-roundtrip($items as item()*, $options as object()?) as item()*
There are two optional parameters than can be supplied using the $options object.
The above optional parameters are refered to as $prefix and $serialization-parameters for convenience.
Error err:XPTY0004 is raised in case one of the parameters is of incorrect type.
This function maps each item of the input sequence to a new item in the output sequence, preserving order.
For convenience, the map is defined recursively from item() to item().
Non-JSON values are encoded to a special object containing two required fields "[$prefix]type" (xs:string) and "[$prefix]value" (xs:string), and two optional fields "[$prefix]prefix" (xs:string) and "[$prefix]encoding-level (xs:integer, strictly positive). An object that has the two required fields, and that has no other field that these four fields, and whose values match the types, is called an Encoded Object.
An object that is not an Encoded Object is mapped to an object with the same keys, and the associated values are obtained by a recursive call on the original values.
An object that is an Encoded Object is left unchanged, except for the field "[$prefix]encoding-level" that is increased by 1 if it exists, or set to 2 if it is absent. This ensures round-trippability of already encoded data.
An array is mapped to an array. Its members are obtained with a recursive call on the members of the original array.
JSON native atomic values (of type exactly xs:double (except infinites and NaN), xs:decimal (except integers), xs:integer, xs:string, xs:boolean or js:null) are mapped to themselves.
XML nodes are mapped to an Encoded Object with two pairs:
  • A pair named "[$prefix]type" and with the value "document-node()", "element()", "text()", "comment()" or "processing-instruction()", depending on the node kind. If it is an attribute or namespace node, err:SENR0001 will be raised by the step below.
  • A pair named "[$prefix]value" and whose value is a serialization of the XML node according to the XML output method and with the serialization parameters specified by $serialization-parameters.
Non-native atomic values that are not qualified names (i.e., neither xs:QName nor xs:NOTATION nor subtypes) are mapped to an Encoded Object with two fields:
  • A field "[$prefix]type" containing the EQName of the atomic type (The XSD namespace may be simply output with the xs: prefix).
  • A field "[$prefix]value" containing the lexical representation of the atomic value.
Non-native atomic values that are qualified names (i.e., xs:QName or xs:NOTATION or subtypes) are mapped to an object with two or three pairs:
  • A field "[$prefix]type" containing the EQName of the atomic type (The XSD namespace may be simply output with the xs: prefix).
  • A field "[$prefix]value" containing the EQName corresponding to the qualified name (which includes namespace and local name).
  • A field "[$prefix]prefix" containing the prefix of the qualified name (only if there is such a prefix).
Example 6.5. Mapping non-JSON values
Query: 
        {
          "serialized XML" :
            jn:encode-for-roundtrip(<para>
                 A pair named "[$prefix]value" (where [$prefix] is replaced with the
                 value of the parameter $prefix) and whose value is a serialization
                 of the XML node according to the XML output method and with the
                 serialization parameters specified by $param.
                 </para>)
        }
Result: 
        {
          "serialized XML" : {
              "Q{http://jsoniq.org/roundtrip}type" : "node()",
              "Q{http://jsoniq.org/roundtrip}value" : "<para>
                 A pair named "[$prefix]value" (where [$prefix] is replaced with the
                 value of the parameter $prefix) and whose value is a serialization
                 of the XML node according to the XML output method and with the
                 serialization parameters specified by $param.
                 </para>"
          }
        }
Query: 
        jn:encode-for-roundtrip({ "nan" : xs:double("NaN"),
                                  "inf" : xs:double("INF"),
                                  "date" : xs:date("1066-10-14"),
                                  "user" : hat:hatSize("M"),
                                  "QName" : xs:QName("jn:encode-for-roundtrip"),
                                  "EQName" : fn:QName("http://jsoniq.org/roundtrip", "value")
                                })
Result: 
        {
          "nan" : {
            "Q{http://jsoniq.org/roundtrip}type" : "xs:double",
            "Q{http://jsoniq.org/roundtrip}value" : "NaN"
          },
          "inf" : {
            "Q{http://jsoniq.org/roundtrip}type" : "xs:double",
            "Q{http://jsoniq.org/roundtrip}value" : "INF"
          },
          "date" : {
            "Q{http://jsoniq.org/roundtrip}type" : "xs:date",
            "Q{http://jsoniq.org/roundtrip}value" : "1066-10-14"
          },
          "hat" : {
            "Q{http://jsoniq.org/roundtrip}type" : "Q{http://www.example.com/hat-shop}hatSize",
            "Q{http://jsoniq.org/roundtrip}value" : "M"
          },
          "QName" : { 
            "Q{http://jsoniq.org/roundtrip}type" : "xs:QName", 
            "Q{http://jsoniq.org/roundtrip}value" : "Q{http://jsoniq.org/functions}encode-for-roundtrip", 
            "Q{http://jsoniq.org/roundtrip}prefix" : "jn" 
          },
          "EQName" : { 
            "Q{http://jsoniq.org/roundtrip}type" : "xs:QName", 
            "Q{http://jsoniq.org/roundtrip}value" : "Q{http://jsoniq.org/roundtrip}value" 
          }
        }