Joins documents into a JSON array document.
<p:declare-step type="p:json-join"> <input port="source" primary="true" content-types="any" sequence="true"/> <output port="result" primary="true" content-types="application/json" sequence="false"/> <option name="flatten-to-depth" as="xs:string?" required="false" select="'0'"/> </p:declare-step>
The p:json-join
step joins the document(s) appearing on the source
port into a JSON array. This array is returned as a single JSON
document on the result
port.
Ports:
Port | Type | Primary? | Content types | Seq? | Description |
---|---|---|---|---|---|
|
|
|
|
| The documents to join. |
|
|
|
|
| The resulting JSON array document containing the source documents. |
Options:
The p:json-join
step takes the document(s) appearing on its source
port and joins them into a JSON array. How the source documents
end up in the resulting array depends on their type:
A JSON source document that is not an array is added to the result as a member of the resulting array.
A JSON source document that is itself an array is also added to the resulting array. However, depending on the value of the
flatten-to-depth
option, additional “flattening” can happen. See Flattening arrays.
An XML, HTML or text document is first serialized (as if written to disk) and then added as a string to the resulting array.
Whether p:json-join
can handle any other media types is implementation-defined and therefore dependent on the XProc processor used.
The resulting array is emitted as a single JSON document on the result
port.
Depending on the value of the flatten-to-depth
option, ”flattening” of the resulting array takes place.
Flattening here means that if there are members of the resulting array that are itself arrays, their members will appear as individual members
in the final result. For instance, flattening ["a", "b", ["c", "d"] ]
results in
["a", "b", "c", "d"]
.
What happens exactly depends on the value of the flatten-to-depth
option:
If 0
(default), no flattening takes place.
If 1
, any array on the source
port is flattened into the final result.
If greater than 1
, flattening is applied recursively to arrays in arrays, up to the given depth.
If unbounded
, all arrays are flattened.
See Flattening arrays for an example.
The following pipeline produces a sequence of 3 documents on the source
port of p:json-join
: An XML, a text and a JSON
document. This is merrily joined into a single array:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <p:inline><some-xml a="b"/></p:inline> <p:inline content-type="text/plain">Hello there!</p:inline> <p:inline content-type="application/json" expand-text="false">{"key": 12345}</p:inline> </p:input> <p:output port="result"/> <p:json-join/> </p:declare-step>
Result document:
["<some-xml a=\"b\"\/>","Hello there!",{"key":12345}]
The following pipeline produces a sequence of 2 documents on the source
port of p:json-join
: A JSON text and a JSON array. If
we do not flatten it, the source array will simply appear as a member of the resulting array:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <p:inline content-type="application/json">"Hello!"</p:inline> <p:inline content-type="application/json">["a", "b", ["c", "d"] ]</p:inline> </p:input> <p:output port="result"/> <p:json-join/> </p:declare-step>
Result document:
["Hello!",["a","b",["c","d"]]]
By setting the flatten-to-depth
option to 1
, the source array is flattened:
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <p:inline content-type="application/json">"Hello!"</p:inline> <p:inline content-type="application/json">["a", "b", ["c", "d"] ]</p:inline> </p:input> <p:output port="result"/> <p:json-join flatten-to-depth="1"/> </p:declare-step>
Result document:
["Hello!","a","b",["c","d"]]
If we increase the flatten-to-depth
option to 2
, the inner array is also flattened. A value
unbounded
would have had the same effect here.
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0"> <p:input port="source" sequence="true"> <p:inline content-type="application/json">"Hello!"</p:inline> <p:inline content-type="application/json">["a", "b", ["c", "d"] ]</p:inline> </p:input> <p:output port="result"/> <p:json-join flatten-to-depth="2"/> </p:declare-step>
Result document:
["Hello!","a","b","c","d"]
No document-properties of the source document(s) survive.
The resulting document has no base-uri
property.
If there are no documents appearing on the source
port, the result
port returns the empty sequence.
This description of the p:json-join
step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).
The formal specification for the p:json-join
step can be found here.
The p:json-join
step is part of categories:
The p:json-join
step is also present in version:
3.0.