p:json-join (3.1) 

Joins documents into a JSON array document.

Summary

<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

source

input

true

any

true

The documents to join.

result

output

true

application/json

false

The resulting JSON array document containing the source documents.

Options:

Name

Type

Req?

Default

Description

flatten-to-depth

xs:string?

false

0

Specifies whether and to which depth JSON source documents that are arrays must be “flattened”. See Flattening arrays.

Please notice that the data type of this option is xs:string (and not xs:integer as you might expect). This is because it can also take the value unbounded.

Description

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.

Flattening arrays

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.

Examples

Basic usage

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}]

Flattening arrays

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"]

Additional details

  • 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.

Errors raised

Error code

Description

XC0111

It is a dynamic error if a document of an unsupported document type appears on port source of p:json-join.

XC0119

It is a dynamic error if flatten is neither “unbounded”, nor a string that may be cast to a non-negative integer.

Reference information

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.