JSON Objects Framework

Go Up to JSON

RAD Studio provides the System.JSON unit, that contains classes and methods to store, parse, and generate data in JSON format.

Note: This page is for the JSON objects framework. To see the other JSON framework that RAD Studio offers, see Readers and Writers JSON Framework.

The JSON objects framework supports all JSON types: 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.UTF8.GetBytes(GJSONString), 0) as TJSONObject;
   
       { output the JSON to console as String }
       Writeln(LJSONObject.ToString);
     finally
       LJSONObject.Free;
     end;
   

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

• Readers and Writers JSON Framework
• BSON
• Serializing User Objects (DataSnap)