JSON Component

Properties Methods Events Configuration Settings Errors

The JSON component can be used to parse and write JSON documents.

Syntax

TiotJSON

Remarks

The JSON component offers a fast and simple way to parse and write information in JSON documents.

Parsing JSON

The JSON component parses JSON documents and verifies that they are well-formed. The results are provided through a set of events.

In addition, the document structure may be queried through an XPath mechanism that supports a subset of the XPath and JSONPath specification.

The parser is optimized for read applications, with a very fast engine that builds internal DOM structures with close to zero heap allocations. Additionally, BuildDOM can be set to False which reduces the overhead of creating the DOM and offers a fast forward-only parsing implementation which fires events to provide the parsed data.

When parsing a document events will fire to provide information about the parsed data. After Parse returns the document may be navigated by setting XPath if BuildDOM is True (default). If BuildDOM is False parsed data is only accessible through the events.

The following events will fire during parsing:

If BuildDOM is True (default), XPath may be set after this method returns. XPath may be set to navigate to specific elements within the JSON document. This will be the path to a specified value within the document. Since arrays in JSON only contain values, and no associated object name, an empty name will be used for these values. To reach an array element at position 1, the path must be set to "[1]". In addition, a root element named "json" will be added to each JSON document in the parser.

BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.

The XPath property accepts both XPath and JSONPath formats. Please see notes below on both formats.

XPath

The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current XPath location.

The following are possible values for an element accessor:


'name'	A particular element name.
[i]	The i-th subelement of the current element.
..	the parent of the current element.

When XPath is set to a valid path the following properties are updated:

BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.

Simple JSON document

{
  "firstlevel": {
    "one": "value",
    "two": ["first", "second"],
    "three": "value three"
  }
}

Example (Setting XPath)


Document root	JsonControl.XPath = "/"
Specific Element	JsonControl.XPath = "/json/firstlevel/one/"
i-th Child	JsonControl.XPath = "/json/firstlevel/two/[i]/"

Note: When using XPath notation the root element is always referred to as "json". As in the above examples this means all paths will begin with "/json".

JSONPath

This property implements a subset of the JSONPath notation. This may be set to point to a specific element in the JSON document.

The JSONPath is a series of one or more accessors in either dot-notation

$.store.book[0].title

Or bracket-notation

$['store']['book'][0]['title']

After setting XPath the following properties are populated:

Examples

Given the following JSON document:

{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            },
            {
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99
            },
            {
                "category": "fiction",
                "author": "J. R. R. Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99
            }
        ],
        "bicycle": {
            "color": "red",
            "price": 19.95
        }
    },
}

The following code shows several examples.

Get the first book's author:

json.XPath = "$.store.book[0].author";
Console.WriteLine(json.XText);
 
//Output
//"Nigel Rees"

Select the first book and inspect the children:

json.XPath = "$.store.book[0]";
Console.WriteLine("Child Count: " + json.XChildren.Count);
Console.WriteLine(json.XChildren[1].Name + ": " + json.XChildren[1].XText);
 
//Output
//Child Count: 4
//author: "Nigel Rees"

Get the price of the second book:

json.XPath = "$['store']['book'][1]['price']";
Console.WriteLine(json.XText);
 
//Output
//12.99

Get the second to last book's author:

json.XPath = "$['store']['book'][last() - 1]['author']";
Console.WriteLine(json.XText);
Console.WriteLine(json.XPath); //Note that "last() - 1" is resolved to "3".
 
//Output
//"Herman Melville"
//$['store']['book'][3]['author']

Display the full subtree at the current path:

json.XPath = "$.store.book[0]";
Console.WriteLine(json.XSubTree);
 
//Output
//            {
//                "category": "reference",
//                "author": "Nigel Rees",
//                "title": "Sayings of the Century",
//                "price": 8.95
//            }

Input Properties

The component will determine the source of the input based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops.

If parsing multiple documents call Reset between documents to reset the parser.

Writing JSON

The JSON component can also be used to create a JSON document.

The document is written to the selected output property. In addition as the document is written, the JSON event will fire. The Text event parameter contains the part of the document currently being written.

Output Properties

The component will determine the destination of the output based on which properties are set.

The order in which the output properties are checked is as follows:

OutputFile
OutputData: The output data is written to this property if no other destination is specified.

Example

Writing a simple JSON document describing a pet:

Json json = new Json();
json.OutputFile = "C:\\temp\\fido.json";
json.StartObject();
json.PutProperty("name", "fido", 2);
json.PutName("previousOwners");
json.StartArray();
json.PutValue("Steve Widgetson", 2);
json.PutValue("Wanda Widgetson", 2);
json.PutValue("Randy Cooper", 2);
json.PutValue("Linda Glover", 2);
json.EndArray();
json.PutProperty("weightUnit", "lbs", 2);
json.PutProperty("weight", "62", 3);
json.EndObject();
json.Flush();

This example results in the following JSON:

{
  "name": "fido",
  "previousOwners": [
    "Steve Widgetson",
    "Wanda Widgetson",
    "Randy Cooper",
    "Linda Glover"
  ],
  "weightUnit": "lbs",
  "weight": 62
}

When writing multiple documents call Reset between documents to reset the writer.

Modifying JSON

The JSON component also allows for modifying existing JSON documents. After loading a JSON document with Parse the document may be editted. The component supports inserting new values, renaming or overwriting existing values, and removing values. After editting is complete call Save to output the updated JSON document.

The following methods are applicable when modifying a JSON document:

When Save is called the modified JSON is written to the specified output location.

Output Properties

The component will determine the destination of the output based on which properties are set.

The order in which the output properties are checked is as follows:

OutputFile
OutputData: The output data is written to this property if no other destination is specified.

Inserting New Values

To insert new values in a JSON document first load the existing document with Parse. Next set XPath to the sibling or parent of the data to be inserted. Call InsertProperty or InsertValue and pass the ValueType and Position parameters to indicate the type of data being inserted and the position.

The ValueType parameter of the above methods specifies the type of the value. Possible values are:

0 (Object)
1 (Array)
2 (String)
3 (Number)
4 (Bool)
5 (Null)
6 (Raw)

The Position parameter of the above methods specifies the position of Value. Possible values are:

0 (Before the current element)
1 (After the current element)
2 (The first child of the current element)
3 (The last child of the current element)

For example:

Given the following JSON:

{
    "store": {
        "books": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
            }
        ]    
    }
}

Insert a new property "price" for each book:

json.XPath = "/json/store/books/[1]";
json.InsertProperty("price", "8.95", 3, 3);  //3 - Number, 3 - Last Child
 
json.XPath = "/json/store/books/[2]";
json.InsertProperty("price", "12.99", 3, 3); //3 - Number, 3 - Last Child
 
json.Save();

Produces the JSON:

{
  "store": {
    "books": [
    {
      "category": "reference",
      "author": "Nigel Rees",
      "title": "Sayings of the Century",
      "price": 8.95
    },
    {
      "category": "fiction",
      "author": "Evelyn Waugh",
      "title": "Sword of Honour",
      "price": 12.99
    }
    ]
  }
}

To add a new book to the array:

json.XPath = "/json/store/books";
json.InsertValue("", 0, 3); //0 - Object, 3 - Last Child
json.XPath = "/json/store/books/[3]";
json.InsertProperty("category", "fiction", 2, 3);        //2 - String, 3 - Last Child
json.InsertProperty("author", "Herman Melville", 2, 3);  //2 - String, 3 - Last Child
json.InsertProperty("title", "Moby Dick", 2, 3);         //2 - String, 3 - Last Child
json.InsertProperty("price", "8.99", 3, 3);              //3 - Number, 3 - Last Child
 
json.Save();

Produces the JSON:

{
  "store": {
    "books": [
    {
      "category": "reference",
      "author": "Nigel Rees",
      "title": "Sayings of the Century",
      "price": 8.95
    },
    {
      "category": "fiction",
      "author": "Evelyn Waugh",
      "title": "Sword of Honour",
      "price": 12.99
    },
    {
      "category": "fiction",
      "author": "Herman Melville",
      "title": "Moby Dick",
      "price": 8.99
    }
    ]
  }
}

To add a new array property to each book:

json.XPath = "/json/store/books/[1]";
json.InsertProperty("tags", "", 1, 2); //1 - Array, 2 - First Child
json.XPath = "/json/store/books/[1]/tags"; 
json.InsertValue("quotes", 2, 3);      //2 - String, 3 - Last Child
json.InsertValue("british", 2, 3);     //2 - String, 3 - Last Child
 
json.XPath = "/json/store/books/[2]";
json.InsertProperty("tags", "", 1, 2); //1 - Array, 2 - First Child
json.XPath = "/json/store/books/[2]/tags";
json.InsertValue("trilogy", 2, 3);     //2 - String, 3 - Last Child
json.InsertValue("war", 2, 3);         //2 - String, 3 - Last Child
 
json.XPath = "/json/store/books/[3]";
json.InsertProperty("tags", "", 1, 2); //1 - Array, 2 - First Child
json.XPath = "/json/store/books/[3]/tags";
json.InsertValue("classic", 2, 3);     //2 - String, 3 - Last Child
json.InsertValue("whales", 2, 3);      //2 - String, 3 - Last Child
 
json.Save();

Producse the JSON:

{
  "store": {
    "books": [
    {
      "tags": ["quotes", "british"],
      "category": "reference",
      "author": "Nigel Rees",
      "title": "Sayings of the Century",
      "price": 8.95
    },
    {
      "tags": ["trilogy", "war"],
      "category": "fiction",
      "author": "Evelyn Waugh",
      "title": "Sword of Honour",
      "price": 12.99
    },
    {
      "tags": ["classic", "whales"],
      "category": "fiction",
      "author": "Herman Melville",
      "title": "Moby Dick",
      "price": 8.99
    }
    ]
  }
}

Removing Values

To remove existing values set XPath and call the Remove method. Continuing with the example above, to remove the first book:

json.XPath = "/json/store/books/[1]";
json.Remove();
 
json.Save();

Produces the JSON:

{
  "store": {
    "books": [
    {
      "tags": ["trilogy", "war"],
      "category": "fiction",
      "author": "Evelyn Waugh",
      "title": "Sword of Honour",
      "price": 12.99
    },
    {
      "tags": ["classic", "whales"],
      "category": "fiction",
      "author": "Herman Melville",
      "title": "Moby Dick",
      "price": 8.99
    }
    ]
  }
}

To remove the "category" properties from each book:

json.XPath = "/json/store/books/[1]/category";
json.Remove();
 
json.XPath = "/json/store/books/[2]/category";
json.Remove();
 
json.Save();

Produces the JSON:

{
  "store": {
    "books": [
    {
      "tags": ["trilogy", "war"],
      "author": "Evelyn Waugh",
      "title": "Sword of Honour",
      "price": 12.99
    },
    {
      "tags": ["classic", "whales"],
      "author": "Herman Melville",
      "title": "Moby Dick",
      "price": 8.99
    }
    ]
  }
}

Updating Existing Names and Values

The SetName and SetValue methods may be used to modify existing names and values. Continuing with the JSON directly above, to rename "tags" to "meta" and update values within the array and prices:

//Rename "tags" to "meta" for 1st book
json.XPath = "/json/store/books/[1]/tags";
json.SetName("meta");
 
//Update Price
json.XPath = "/json/store/books/[1]/price";
json.SetValue("13.99", 3); //3 - Number
 
//Rename "tags" to "meta" for 2nd book
json.XPath = "/json/store/books/[2]/tags";
json.SetName("meta");
 
//Update tag "whales" to "revenge"
json.XPath = "/json/store/books/[2]/meta/[2]";
json.SetValue("revenge", 2); //2 - String
 
//Update Price
json.XPath = "/json/store/books/[2]/price";
json.SetValue("9.99", 3); //3 - Number
 
json.Save();

Produces the JSON:

{
  "store": {
    "books": [
    {
      "meta": ["trilogy", "war"],
      "author": "Evelyn Waugh",
      "title": "Sword of Honour",
      "price": 13.99
    },
    {
      "meta": ["classic", "revenge"],
      "author": "Herman Melville",
      "title": "Moby Dick",
      "price": 9.99
    }
    ]
  }
}

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.


BuildDOM	When True, an internal object model of the JSON document is created.
InputData	The JSON data to parse.
InputFile	The file to process.
OutputData	The output JSON after processing.
OutputFile	The path to a local file where the output will be written.
Overwrite	Indicates whether or not the component should overwrite files.
Validate	When True, the parser checks that the document consists of well-formed XML.
XChildren	Collection of child elements of the current element.
XElement	The name of the current element.
XElementType	Indicates the data type of the current element.
XErrorPath	An XPath to check the server response for errors.
XParent	The parent of the current element.
XPath	Provides a way to point to a specific element in the response.
XSubTree	A snapshot of the current element in the document.
XText	The text of the current element.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.


Config	Sets or retrieves a configuration setting.
EndArray	Writes the closing bracket of a JSON array.
EndObject	Writes the closing brace of a JSON object.
Flush	Flushes the parser's or writer's buffers.
HasXPath	Determines whether a specific element exists in the document.
InsertProperty	This method inserts the specified name and value at the selected position.
InsertValue	This method inserts the specified value at the selected position.
LoadSchema	Load the JSON schema.
Parse	This method parses the specified JSON data.
PutName	Writes the name of a property.
PutProperty	Write a property and value.
PutRaw	Writes a raw JSON fragment.
PutValue	Writes a value of a property.
Remove	Removes the element or value set in XPath.
Reset	Resets the component.
Save	Saves the modified JSON document.
SetInputStream	Sets the stream from which the component will read data to parse.
SetElementName	Sets a new name for the element specified by XPath.
SetOutputStream	The stream to which the component will write the JSON.
SetValue	Sets a new value for the element specified by XPath.
StartArray	Writes the opening bracket of a JSON array.
StartObject	Writes the opening brace of a JSON object.
TryXPath	Navigates to the specified XPath if it exists.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.


Characters	Fired for plain text segments of the input stream.
EndDocument	Fires when the end of a JSON document is encountered.
EndElement	Fired when an end-element tag is encountered.
Error	Information about errors during data delivery.
IgnorableWhitespace	Fired when a section of ignorable whitespace is encountered.
JSON	Fires with the JSON data being written.
StartDocument	Fires when the start of a new JSON document is encountered.
StartElement	Fired when a new element is encountered in the document.

Configuration Settings

The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.


CacheContent	If true, the original JSON is stored internally in a buffer.
CloseInputStreamAfterProcess	Determines whether or not the input stream is closed after processing.
CloseOutputStreamAfterProcess	Determines whether or not the output stream is closed after processing.
ElementXPath	The XPath value for the current element in the document.
EscapeForwardSlashes	Whether to escape forward slashes when writing a JSON object.
InputFormat	Specifies the input format used in JSON streaming.
PrettyPrint	Determines whether output is on one line or "pretty printed".
RecordEndDelimiter	The character sequence after the end of a JSON document.
RecordStartDelimiter	The character sequence before the start of a JSON document.
StringProcessingOptions	Defines options to use when processing string values.
XPathNotation	Specifies the expected format when setting XPath.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
UseInternalSecurityAPI	Tells the component whether or not to use the system security libraries or an internal implementation.

IPWorks IoT 2020 Delphi Edition

JSON Component

Syntax

Remarks

Parsing JSON

XPath

JSONPath

Writing JSON

Modifying JSON

Property List

Method List

Event List

Configuration Settings

Questions / Feedback?