FME Transformers: 2026.1

Categories
Format Specific

Format Specific

Web

Web

Categories
Format Specific

Format Specific

Web

Web

JSONAppender

Assembles multiple JSON fragments into a single JSON document.

The transformer has two input ports: one accepting a single JSON document, and another accepting multiple JSON fragments.

The JSONAppender appends each fragment to the end of the JSON array specified by the JSON Pointer to Append Location parameter. Each fragment is inserted as a single JSON value, regardless of type. If the key matching the final token in the pointer does not exist at the specified location, the transformer will create that key and initialize it as a new array before appending the fragments.

Optional Input Ports

This transformer has two modes, depending on whether input features are received via the Document and Fragment ports.

  • Input-driven: When input features are connected, the transformer runs according to the features received.
  • Run Once: If the input ports are not used, the transformer runs one time.

JSON Pointers

A JSON pointer is a simple mechanism to refer to values within a JSON document. It is defined by RFC 6901 and consists of a sequence of tokens separated by forward slashes (/). Each token selects an object key or array index. An empty JSON Pointer refers to the root JSON value. For example, given the JSON document:

Copy 
{
  "metadata" : {
    "title" : "Value List",
    "count" : 2
  }
  "items" : ["a", "b"]
}

The following JSON Pointers evaluate as:

“”

The entire document

“/metadata/title”

"Value List"

“/items”

["a", "b"]

“/items/0”

"a"

The JSON Pointer is used by this transformer to determine where incoming fragments should be appended.

See JavaScript Object Notation (JSON) Pointer at the IETF (RFC 6901).

Configuration

Input Ports

Input features containing the main JSON document.

Input features containing the JSON fragments.

Output Ports

This is the output for the main JSON document with the appended fragments.

A JSON document is output via this port when no fragments are appended or when additional documents occur in the same group.

Multiple main documents are allowed only if the Group By parameter is used, otherwise the duplicate documents are output via this port.

The main documents are considered a duplicate of each other when the values of their composite Group By key equal.

Fragments that were not appended or have no corresponding Group By main JSON document are output via this port.

Documents or fragments that do not contain valid JSON are sent to this port. Rejected fragments do not halt processing, any remaining fragments continue to be evaluated.

Parameters

Group By

Use this parameter to organize multiple main documents and fragments into groups. Multiple main JSON documents are allowed when their composite Group By key differs. Unused documents and fragments, those without corresponding keys, are routed to the UnusedDocument and UnusedFragment ports, respectively.

Complete Groups

Select the point in processing at which groups are processed:

When All Features Received

This is the default behavior. Processing will only occur in this transformer once all input is present.

When Group Changes (Advanced)

This transformer will process input groups in order. Changes of the value of the Group By parameter on the input stream will trigger processing on the currently accumulating group. This may improve overall speed (particularly with multiple, equally-sized groups), but could cause undesired behavior if input groups are not truly ordered.

There are two typical reasons for using When Group Changes (Advanced) . The first is incoming data that is intended to be processed in groups (and is already so ordered). In this case, the structure dictates Group By usage - not performance considerations.

The second possible reason is potential performance gains.

Performance gains are most likely when the data is already sorted (or read using a SQL ORDER BY statement) since less work is required of FME. If the data needs ordering, it can be sorted in the workspace (though the added processing overhead may negate any gains).

Sorting becomes more difficult according to the number of data streams. Multiple streams of data could be almost impossible to sort into the correct order, since all features matching a Group By value need to arrive before any features (of any feature type or dataset) belonging to the next group. In this case, using Group By with When All Features Received may be the equivalent and simpler approach.

Note  Multiple feature types and features from multiple datasets will not generally naturally occur in the correct order.

As with many scenarios, testing different approaches in your workspace with your data is the only definitive way to identify performance gains.

JSON Document Input

Selecting from the list enables that selection's corresponding parameter:

  • Attribute with JSON Document: Choose the attribute containing the main JSON document.
  • JSON Document Filename: Browse to the JSON file.

JSON Pointer to Append Location

A standard RFC 6901 JSON Pointer is used to identify the location in the JSON document where fragments will be appended. The parameter’s default value is an empty string, which refers to the root element.

Consider the following JSON document:

Copy 
{
  "data": {
    "metadata": {
      "title": "test",
      "time": "2:30"
    },
    "groups": ["A","B"]
  }
}

And the following JSON fragment:

Copy 
{
  "fragment" : "value"
}

If the pointer resolves to an existing array, the fragments will be appended to the end of that array. For example, using the pointer /data/groups produces:

Copy 
{
  "data": {
    "metadata": {
      "title": "test",
      "time": "2:30"
    },
    "groups": ["A","B",{"fragment" : "value"}]
  }
}

If all Pointer tokens exist in the document except for the last token, the transformer will create a new key from the final token, initialize it with a new JSON array, and append the fragments to the newly created array. For example, using the pointer /data/metadata/results produces:

Copy 
{
  "data": {
    "metadata": {
      "title": "test",
      "time": "2:30",
      "results": [{"fragment" : "value"}]
     },
     "groups": ["A","B"]
  }
}

If the pointer does not resolve to an existing array and a new array cannot be created under the final key, the append location is considered unresolvable. This can occur when the portion of the pointer preceding the final token does not exist in the document (e.g. /data/tests/trials) or when the pointer refers to something other than an array, such as an array element (/data/groups/0) or a non-array value (/data/metadata/title).

In these cases both the document and fragment are routed to the UnusedDocument and UnusedFragment ports, respectively.

JSON Fragment Input

Selecting from the list enables that selection's corresponding parameter:

  • Attribute with JSON Fragment: Choose the attribute containing the JSON Fragment.
  • JSON Fragment Filename: Browse to the JSON file.

Encoding

This parameter is used to select the encoding for the appended results.

Output Attribute

The name of the attribute to contain the appended JSON document.

Editing Transformer Parameters

Transformer parameters can be set by directly entering values, using expressions, or referencing other elements in the workspace such as attribute values or user parameters. Various editors and context menus are available to assist. To see what is available, click beside the applicable parameter.

Defining Values

There are several ways to define a value for use in a Transformer. The simplest is to simply type in a value or string, which can include functions of various types such as attribute references, math and string functions, and workspace parameters.

Using the Text Editor

The Text Editor provides a convenient way to construct text strings (including regular expressions) from various data sources, such as attributes, parameters, and constants, where the result is used directly inside a parameter.

Text Editor

Using the Arithmetic Editor

The Arithmetic Editor provides a convenient way to construct math expressions from various data sources, such as attributes, parameters, and feature functions, where the result is used directly inside a parameter.

Arithmetic Editor

Conditional Values

Set values depending on one or more test conditions that either pass or fail.

Parameter Condition Definition Dialog

Content

Expressions and strings can include a number of functions, characters, parameters, and more.

When setting values - whether entered directly in a parameter or constructed using one of the editors - strings and expressions containing String, Math, Date/Time or FME Feature Functions will have those functions evaluated. Therefore, the names of these functions (in the form @<function_name>) should not be used as literal string values.

String Functions

These functions manipulate and format strings.

Special Characters

 A set of control characters is available in the Text Editor.

Math Functions

Math functions are available in both editors.
Date/Time Functions Date and time functions are available in the Text Editor.

Math Operators

These operators are available in the Arithmetic Editor.

FME Feature Functions

These return primarily feature-specific values.

FME Parameters

FME and workspace-specific parameters may be used.
Creating and Modifying User Parameters Create your own editable parameters.

Table Tools

Transformers with table-style parameters have additional tools for populating and manipulating values.

Row Reordering

Enabled once you have clicked on a row item. Choices include:

  • Add a row
  • Remove a row
  • Move current row up one
  • Move current row down one
  • Move current row to top
  • Move current row to bottom

Cut, Copy, and Paste

Enabled once you have clicked on a row item. Choices include:

  • Cut a row - delete and copy to clipboard
  • Copy a row to the clipboard
  • Paste a row from the clipboard

Cut, copy, and paste may be used within a transformer, or between transformers.

Filter

Start typing a string, and the matrix will only display rows matching those characters. Searches all columns. This only affects the display of attributes within the transformer - it does not alter which attributes are output.

Import

Import populates the table with a set of new attributes read from a dataset. Specific application varies between transformers.

Reset/Refresh

Generally resets the table to its initial state, and may provide additional options to remove invalid entries. Behavior varies between transformers.

Note: Not all tools are available in all transformers.

For more information, see Transformer Parameter Menu Options.

Reference

Processing Behavior

Group-Based

Feature Holding

Yes
Dependencies None
Aliases  
History  

FME Online Resources

The FME Community and Support Center Knowledge Base have a wealth of information, including active forums with 35,000+ members and thousands of articles.

Search for all results about the JSONAppender on the FME Community.

 

Examples may contain information licensed under the Open Government Licence – Vancouver, Open Government Licence - British Columbia, and/or Open Government Licence – Canada.