mORMot Open Source

zen010101

Member

Registered: 2024-06-15

Posts: 167

New Wiki Article: JSON Processing Guide (IDocDict/IDocList)

Hi all,

  Following the RawUtf8 guide, I've created a comprehensive guide for mORMot 2's JSON processing interfaces - IDocList, IDocDict, and IDocDicts.

  Wiki Link: https://github.com/zen010101/Claude_Mor … sing-Guide

  The guide is organized into 15 chapters covering:

  - Core Concepts - What are IDocList/IDocDict, design philosophy, relationship with TDocVariant
  - Type System - Interface hierarchy, IDocDicts array type, TDocVariantModel options
  - Creating Instances - Factory functions (DocList, DocDict, DocListFromResults, DocDictDynArray)
  - IDocList Guide - Element access, iteration, filtering, sorting
  - IDocDict Guide - Key access, path-based navigation (PathDelim), iteration
  - IDocDicts Guide - Working with arrays of IDocDict
  - ORM Integration - jsonfromresults parameter, expanded vs non-expanded formats
  - Serialization - JSON output formats (compact, human-readable)
  - Error Handling - Parse failure behaviors, validation patterns
  - Performance - Typed accessors, Sort for O(log n) lookup, model selection
  - Memory Management - Weak references vs deep copies, Objects iterator pitfalls
  - API Reference - Complete method signatures
  - Practical Examples - Real-world usage patterns
  - FAQ - Common questions and solutions

  All code examples have been validated through unit tests (455 assertions passed).

  Hope this helps those working with JSON in mORMot 2. Feedback and corrections are welcome!

ab

Administrator

From: France

Registered: 2010-06-21

Posts: 15,367

Website

Re: New Wiki Article: JSON Processing Guide (IDocDict/IDocList)

Very nice and impressive!
The output is really exhaustive.

Some minor remarks:
1) some sample code use "record" as local variable name - I am not sure it would compile as such on all compilers (maybe).
2) IDocDict sorted insertion/deletion is O(log(n)) not O(n).
3) it is weird to recommend jsonHumanReadable for Log Files, because log entries are on a single line so there is the line feeds are trimmed at output: I guess jsonUnquotedPropName makes more sense.
4) the "CRITICAL: Register at startup" info for records is not true if you expect to use the extended RTTI for Delphi 2010+. You need to register only if you need to register the fields from text.
5) in chapter 9, the property access seems incorrect - I guess IDocDict.Get() returns a boolean, not a value, and is the proper pattern to use instead of Exists() + I[].
6) the values in chapter 10 "performance" seems sometimes odd to me: there should be no difference in parsing between models. And sometimes incorrect, e.g. the "list" instance is not freed before filling, so the measurements take the release into their timing.
7) instead of using nested IDocList/IDocDict() calls, the name/value pairs could in fact use '[' and ']' or '{' and '}' for nested arrays and objects.

mrbar2000

Member

From: Brazil

Registered: 2016-10-26

Posts: 113

Re: New Wiki Article: JSON Processing Guide (IDocDict/IDocList)

Very good explain. for more doccumentation so!
Congratulations

zen010101

Member

Registered: 2024-06-15

Posts: 167

Re: New Wiki Article: JSON Processing Guide (IDocDict/IDocList)

Thank you very much, Arnaud! Your detailed review is invaluable.

  I've addressed all the issues in the latest update:

  1. Record variable name - Fixed the reserved word issue
  2. O(n) complexity - Corrected to O(log n) for sorted IDocDict lookup
  3. Log format - Changed recommendation from jsonHumanReadable to jsonUnquotedPropNameCompact (grep-friendly, single line per entry)
  4. RTTI clarification - Added note that Rtti.RegisterType is mainly needed for FPC stable versions; Delphi 2010+ has enhanced RTTI for basic serialization
  5. Get() methods - Rewrote section to show all 11 boolean-returning overloads with proper usage patterns
  6. Performance chapter - Deleted due to measurement errors (now 14 chapters total)
  7. Native nested syntax - Added documentation for the '{' '}' '[' ']' delimiter syntax

  The wiki has been updated and chapters renumbered accordingly.

ab

Administrator

From: France

Registered: 2010-06-21

Posts: 15,367

Website

Re: New Wiki Article: JSON Processing Guide (IDocDict/IDocList)

Nice!

Note that Rtti.RegisterType() is not enough for FPC stable. We need to call Rtti.RegisterFromText() with manual field description as text on this target (or oldest Delphi).

But I am not so sure about the '[' '{' trick any more... it is not supported in TDocVariant/IDocAny.
This trick is supported in Bson() and JsonEncode().

And I am not so sure either that nested IDocDict() is actually working as Claude is expecting here... I suspect the interface values are not supported and would trigger ESynVariant 'unhandled TVarRec.VType'.

I would not use IDocDict/IDocList for generating JSON anyway for any SOA service.
But return a RawJson and use JsonEncode().

zen010101

Member

Registered: 2024-06-15

Posts: 167

Re: New Wiki Article: JSON Processing Guide (IDocDict/IDocList)

Thank you ab for the valuable feedback! I have updated the JSON wiki documentation accordingly:

  1. Delimiter Syntax Clarification

  Fixed the documentation to clarify that `'{' '}' '[' ']'` delimiter syntax is supported by `JsonEncode()` only, NOT by `DocDict()`/`DocList()`. All examples now correctly use `.AsVariant` for nesting:

  // CORRECT for DocDict/DocList
  dict := DocDict([
    'user', DocDict([
      'name', 'Alice',
      'roles', DocList(['admin', 'user']).AsVariant
    ]).AsVariant
  ]);

  2. SOA Service Best Practices

  Added documentation recommending RawJson + JsonEncode() for SOA interface-based services instead of IDocDict/IDocList:
  - New section in Chapter 3: "SOA Service Considerations"
  - New FAQ Q16: "Should I use IDocDict/IDocList in SOA service methods?"
  - Notes added to API response examples

  3. FPC Stable RTTI Registration

  - Rtti.RegisterType() is NOT enough for FPC stable or older Delphi
  - Must use Rtti.RegisterFromText() with manual field description

  Thanks again for the corrections!