encoding.json is a library for Delphi that uses RTTI and generics to encode/decode JSON data into/from Delphi types.
It accepts every document of the JSONTestSuite conformance corpus that a parser must accept, and rejects every one it must reject.
Why another JSON library: see Motivation. This repo contains AI-generated code.
Licensed under the zlib license — free for any use, commercial applications included.
The library comes as a single file. Just drop source/encoding.json.pas into your project.
Tested on: Delphi 12 Athens, Win32 and Win64 - the whole suite, on both, by
runtests.bat. Nothing else is tested: other Delphi versions and the macOS, iOS, Android and
Linux targets may well work, but I haven't compiled the unit for them, let alone run it.
JSON is a ready-made global instance. Everything below is a method on that instance,
not a class method.
To encode, use either:
JSON.Marshal( myRecordObjectOrArray , myString );or, if you want pretty-printing:
JSON.MarshalIndent( myRecordObjectOrArray , '<indent>', myString );To decode, just:
JSON.Unmarshal( myJsonString, myRecordObjectOrArray );The string can be a UnicodeString or a UTF8String in either direction. Unmarshal also
takes a PAnsiChar and a length, so a buffer can be decoded without copying it into a
string first.
Consider this structure:
TPerson = record
FirstName: string;
LastName: string;
end;To encode an item of this structure to JSON, just:
uses encoding.json;
...
var somePerson: TPerson;
somePerson.FirstName:= 'John';
somePerson.LastName:= 'Lennon';
var someJSON: UTF8String;
JSON.Marshal(somePerson,someJSON);
// someJSON is now {"FirstName":"John","LastName":"Lennon"}Every entry point returns a result code rather than raising — see
Error handling. For the cases where a result code is more
ceremony than the call is worth, Marshal and MarshalIndent also come as
one-argument functions that return the document and raise EJSONError if it cannot
be produced:
Send( JSON.Marshal(somePerson) );
writeln( JSON.MarshalIndent(somePerson,' ') );Nothing in the public API raises, with one deliberate exception: the Marshal and
MarshalIndent overloads above that return the document. Everything else returns a
TJSONResult, and JSONOK is the only value that means success:
if JSON.Unmarshal(someJSON,somePerson) <> JSONOK then
// ...nothing was written that you can rely onWhat each code means, how to get the byte offset or the failing member, and what a failed decode leaves behind in your variable are in docs/errors.md.
The global JSON instance is created with JSONDefaultConfig. Settings live in a
TJSONConfig, which you can pass to the constructor of your own instance or hand to
Configure:
var cfg := JSON.Config; // start from what is already there
cfg.DateTimeFormat := jdfEpoch;
cfg.SortKeys := true;
JSON.Configure(cfg);Configure is not thread-safe — call it before the instance is shared. Every setting,
how to create an instance of your own, and the rules for key order and dates are in
docs/configuration.md.
- Supports all simple types:
Integers, Floats, Strings, Booleans - Supports
ClassesandRecords, will encode/decode all publicly visible fields (and properties, in case of classes). A property counts in the direction it supports: a read-only one is encoded and never decoded, a write-only one is decoded and never encoded. The exception is a property of class type: it is decoded into the instance its getter returns, read-only or not, and its setter is not called - soproperty Items: TObjectList<T> read FItemsround-trips. The setter is only used when the getter returnsnil, and fornull. - Supports generic types
TList<T>, TDictionary<K,V>and its descendants. A JSON key is text, soKis astring,AnsiString,UTF8StringorWideString; any other key type - aShortStringincluded - is refused withJSONUnsupportedType - Special support for
TStringListto handle both lists of strings as well as key-value-maps TColorencodes as a web colour,"#rrggbb"— the byte order is swapped, because Delphi stores$00bbggrr- Support for
TGUID, written in lower case as RFC 4122 asks, read in either case char,AnsiCharandWideCharencode as a one-character string- Enumerations encode as the name of their value,
"seSecond"; a name that is not a member is refused when decoding Setsover an enumeration encode as an array of member names. Decoding is deliberately forgiving:nulland[]both mean the empty set, and a member named twice is not an errorTDateTime,TDateandTTimeencode as RFC 3339, unix epoch seconds or epoch milliseconds; whether a value in memory is UTC or local time is a config parameterCurrencyis written exactly, from its scaled integer, not through a floatPointertypes for all types mentioned above are supported- Dynamic documents (experimental): a
Variantdestination accepts any JSON, whatever its shape - objects become aTVarDictreached by name, arrays a native variant array - Rename, skip or omit-empty attribute
[JSON] - Custom parsers and formatters for any type, replacing a built-in or building on one
- Single-line decoding/encoding, with
Marshal/MarshalIndentoverloads that return the document for use as an expression - A single file
- Light on heap allocations
- Result codes instead of exceptions, with optional detail (offset, depth, failing member)
- 224 DUnitX tests, plus every file of the
JSONTestSuite conformance corpus as a case of its
own, and the 95 files that must be accepted once more through a
Variant- 637 in all
Some behaviour could reasonably have gone the other way, and a few things Delphi's RTTI does not allow at all. Both are listed in docs/limits-and-gotchas.md - worth a read before one of them surprises you.
For quite some time I really wanted something like the encoding/json package from Go (https://pkg.go.dev/encoding/json) in Delphi. To be precise, I was looking for something simple and worry-free. Neither would it be necessary to be super-performant, nor would it need to support every edge case. Decoding/encoding should work with a single line of code and it shouldn't be mandatory to amend your types to make them work with the library.
While there are existing solutions - like the excellent mORMot and Grijjy libraries, not to forget the built-in REST.Json unit - each of those had some drawbacks I did not like:
- Some are embedded in bigger frameworks/libraries and increase the amount of dead weight you have to carry in your project.
- You mostly see a focus on classes, less on records and the rest of Delphi's type system.
- Some require you to make your types "fit" the encoder/decoder.
I thought there was room for another take on this topic that addresses exactly these points:
- It's a single file you can drop into your project.
- It covers all of the important cases/types.
- There are attributes, but they're optional.
On top of that there were a couple of other things on my wishlist:
- I want to have good test coverage, so I have a high confidence this stuff works.
- I want to have the TStrings/TStringList/TDictionary/TList types directly supported.
Since people tend to fight over this: yes, this repo contains AI-generated code. I worked on the library in the little spare time I have, until at some point it turned into a total rabbit hole (as it always does - in this case, correctness and completeness). I had a working library, but a much weaker one than what's here now. I heavily used Claude Opus 5.5 to turn it into what it is now.
I reviewed every change, and the 637 tests, including the full JSONTestSuite corpus, are what I rely on to know it's correct.
zlib. Fork it, copy it, change it, ship it inside commercial products — there is nothing to sign and nothing to pay. All it asks is that you do not claim you wrote the original, that modified versions say they are modified, and that the notice stays in the source.
The single file carries the full notice in its header, which is the copy that matters: the
unit is meant to be dropped into a project on its own, and a repository LICENSE does not
travel with it.
The test data in testdata/ is not covered by it: it comes from three other projects and
keeps their licenses, MIT and BSD-3-Clause — see testdata/README.md.
Not a condition of the license. encoding.json is free for any use, and nothing is withheld from you if you skip this section entirely.
That said, if it saves you time in something you sell, either an acknowledgment in your documentation or a donation of whatever you think it is worth would be appreciated: