JSON

Go Up to Using the RTL in Multi-Device Applications

JSON (JavaScript Object Notation) is a lightweight data-interchange format that can be used as an alternative to other data-interchange formats such as XML or YAML. RAD Studio provides a unit, System.JSON, that contains classes and methods to store, parse and generate data in JSON format.

All JSON types are supported: TJSONObject, TJSONArray, TJSONNumber, TJSONString, TJSONTrue, TJSONFalse, TJSONNull -- all descendants of TJSONValue.

JSON objects can be instantiated and incrementally constructed, or a byte stream can be parsed into one.

In the code snippet below, an object with a "Hello": "World" pair is created:

var
  LJSONObject: TJSONObject;

begin
  LJSONObject:= TJSONObject.Create;
  LJSONObject.AddPair(TJSONPair.Create(TJSONString.Create('Hello'),
                                       TJSONString.Create('World')));

The static class function ParseJSONValue or the function Parse can be used to parse the byte stream into the equivalent JSON value instance.

  class function ParseJSONValue(const Data: TBytes; const Offset: Integer): TJSONValue; overload; static;

For instance, given:

const
  GJSONString =
    '{' +
    '    "name": {'+
    '        "A JSON Object": {' +
    '          "id": "1"' +
    '        },' +
    '        "Another JSON Object": {' +
    '          "id": "2"' +
    '        }' +
    '    },' +
    '    "totalobjects": "2"' +
    '}';

you can transform the JSON string representation into a JSON with one of the following code snippets.

1. Using ParseJSONValue:

procedure ConsumeJsonString;
var
  LJSONObject: TJSONObject;

begin
  LJSONObject := nil;
  try
    { convert String to JSON }
    LJSONObject := TJSONObject.ParseJSONValue(TEncoding.ASCII.GetBytes(GJSONString), 0) as TJSONObject;

    { output the JSON to console as String }
    Writeln(LJSONObject.ToString);
  finally
    LJSONObject.Free;
  end;

1. Using Parse:

procedure ConsumeJsonBytes;
var
  LJSONObject: TJSONObject;

begin
  LJSONObject := nil;
  try
    LJSONObject := TJsonObject.Create;
    { convert String to JSON }
    LJSONObject.Parse(BytesOf(GJSONString), 0);

    { output the JSON to console as String }
    Writeln(LJSONObject.ToString);
  finally
    LJSONObject.Free;
  end;
end;

Both snippets would produce at the console:

{"name":{"A JSON Object":{"id":"1"},"Another JSON Object":{"id":"2"}},"totalobjects":"2"}

Lifecycle

In JSON, the parent object owns any of the values it contains, unless the Owned property is set to False. In this case, the destruction of a JSON array object skips each member that has the flag set to False. This feature allows the combination of various objects into bigger objects while retaining ownership. By default, the property is True, meaning all contained instances are owned by their parent.

Cloning

All JSON types can be cloned. The cloning operation is a deep clone. The cloned object will own all of the JSON instances.

Server methods accept all JSON types as input, output, or return parameters. But they do not own any of them. The JSON instances are freed after the server method executes. One can read the JSON objects and react to the content, but if further storage is required, then the object must be cloned.

See Also

• Serializing User Objects (DataSnap)