Skip to content

Commit

Permalink
Revise ordering rules for parse-json, xml-to-json, json-to-xml.
Browse files Browse the repository at this point in the history
  • Loading branch information
@michaelhkay
michaelhkay committed Nov 27, 2024
1 parent 1d8337e commit 6a5671d
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 30 deletions.
50 changes: 21 additions & 29 deletions specifications/xpath-functions-40/src/function-catalog.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23724,7 +23724,7 @@ declare function map:find($input as item()*,
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="564"><p>Enhanced to allow for ordered maps.</p></fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
</fos:changes>
</fos:function>

Expand Down Expand Up @@ -23833,23 +23833,25 @@ declare function map:find($input as item()*,
4: "Donnerstag", 5: "Freitag", 6: "Samstag", -1: "Unbekannt" }</eg></fos:result>
</fos:test>
<fos:test>
<fos:expression><eg>map:put(parse-json('{ "red": 0, "green": 1, "blue" 2 }),
"yellow", -1) => map:keys()</eg></fos:expression>
<fos:expression><eg>parse-json('{ "red": 0, "green": 1, "blue" 2 }', {'retain-order': true()})
=> map:put("yellow", -1)
=> map:keys()</eg></fos:expression>
<fos:result>"red", "green", "blue", "yellow"</fos:result>
<fos:postamble>The result of <code>fn:parse-json</code> has <code>ordering=insertion</code>,
<fos:postamble>The result of <code>fn:parse-json</code> is in insertion order,
so the new entry is added at the end of the list.</fos:postamble>
</fos:test>
<fos:test>
<fos:expression><eg>map:put(parse-json('{ "red": 0, "green": 1, "blue" 2 }),
"red", -1) => map:keys()</eg></fos:expression>
<fos:expression><eg>parse-json('{ "red": 0, "green": 1, "blue" 2 }', {'retain-order': true()})
=> map:put("red", -1)
=> map:keys()</eg></fos:expression>
<fos:result>"red", "green", "blue"</fos:result>
<fos:postamble>The result of <code>fn:parse-json</code> has <code>ordering=insertion</code>,
changing the value for an existing key does not change the order of the keys.</fos:postamble>
<fos:postamble>The result of <code>fn:parse-json</code> is in insertion order,
so changing the value for an existing key does not change the order of the keys.</fos:postamble>
</fos:test>
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="564"><p>Enhanced to allow for ordered maps.</p></fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
</fos:changes>
</fos:function>

Expand Down Expand Up @@ -24033,7 +24035,7 @@ map:filter($map, fn($k, $v) { not(some($keys, atomic-equal($k, ?))) })
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="564"><p>Enhanced to allow for ordered maps.</p></fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
</fos:changes>
</fos:function>
<fos:function name="for-each" prefix="map">
Expand Down Expand Up @@ -24122,7 +24124,7 @@ return <box>{
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="564"><p>Enhanced to allow for ordered maps.</p></fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
</fos:changes>
</fos:function>

Expand Down Expand Up @@ -24203,7 +24205,7 @@ map:for-each($map, fn($key, $value) {
<fos:change issue="1171" PR="1182" date="2024-05-07">
<p>The <code>$predicate</code> callback function may return an empty sequence (meaning <code>false</code>).</p>
</fos:change>
<fos:change issue="564"><p>Enhanced to allow for ordered maps.</p></fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27"><p>Enhanced to allow for ordered maps.</p></fos:change>
</fos:changes>
</fos:function>

Expand Down Expand Up @@ -24647,7 +24649,7 @@ return map:build($titles/title, fn($title) { $title/ix })
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="564"><p>New in 4.0</p></fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27"><p>New in 4.0</p></fos:change>
</fos:changes>
</fos:function>

Expand Down Expand Up @@ -24748,7 +24750,7 @@ return
</fos:example>
</fos:examples>
<fos:changes>
<fos:change issue="564"><p>New in 4.0</p></fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27"><p>New in 4.0</p></fos:change>
</fos:changes>
</fos:function>

Expand Down Expand Up @@ -25205,19 +25207,6 @@ return $M(collation-key("a", $C))</eg></fos:expression>
</fos:value>
</fos:values>
</fos:option>

<fos:option key="retain-order">
<fos:meaning>Determines whether the XML representation of a JSON object should retain the order
of entries in the input.</fos:meaning>
<fos:type>xs:boolean</fos:type>
<fos:default>true</fos:default>
<fos:values>
<fos:value value="false">The children of any <code>fn:map</code> element in the output will be
in <termref def="implementation-dependent"/> order.</fos:value>
<fos:value value="true">The children of any <code>fn:map</code> element in the output will be
in the same order as the corresponding entries in the JSON input.</fos:value>
</fos:values>
</fos:option>

<fos:option key="validate">
<fos:meaning>Determines whether the generated XML tree is schema-validated.</fos:meaning>
Expand Down Expand Up @@ -25377,8 +25366,8 @@ return $M(collation-key("a", $C))</eg></fos:expression>
<p>The XDM tree returned by the function does not contain any
unnecessary (albeit valid) nodes such as whitespace text nodes, comments, or processing instructions.
It does not include any whitespace in the value of <code>number</code> or <code>boolean</code>
element nodes, <phrase>or in the value of <code>escaped</code> or <code>escaped-key</code>
attribute nodes.</phrase></p>
element nodes, nor in the value of <code>escaped</code> or <code>escaped-key</code>
attribute nodes.</p>


<p>If the result is typed, every element named <code>string</code> will have an attribute named
Expand Down Expand Up @@ -27459,6 +27448,9 @@ return <csv xmlns="http://www.w3.org/2005/xpath-functions"> {
specification gave the default value as <code>true</code>, but this appears to have been an error,
since it was inconsistent with examples given in the specification and with tests in the test suite.</p>
</fos:change>
<fos:change issue="564" PR="1609" date="2024-11-27">
<p>An option is provided to retain the order of entries in maps.</p>
</fos:change>
</fos:changes>
</fos:function>

Expand Down
2 changes: 1 addition & 1 deletion specifications/xpath-functions-40/src/xpath-functions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6854,7 +6854,7 @@ correctly in all browsers, depending on the system configuration.</emph></p>-->
of numbers, the conversion is not guaranteed to retain full precision.</p>

<p>Although the order of entries in a JSON object is generally considered to have no significance, the functions
<code>json-to-xml</code> and <code>json-to-xml</code> both retain order.</p>
<code>json-to-xml</code> and <code>xml-to-json</code> both retain order.</p>

<p>The XDM representation of a JSON value may either be untyped (all elements annotated as <code>xs:untyped</code>, attributes
as <code>xs:untypedAtomic</code>), or it may be typed. If it is typed, then it <rfc2119>must</rfc2119> have the type
Expand Down

0 comments on commit 6a5671d

Please sign in to comment.