Neon JSON Serialization for Delphi

Neon determines serialization and deserialization capability based on the RTTI read and write clauses of a property.

Serialization (Writing JSON)

By default, read-only properties are included in the JSON. To exclude them, use:

LConfig := TNeonConfiguration.Default.SetIgnoreReadOnlyProps(True);

Exemption: A read-only property of a class or interface type is always kept in the JSON to ensure composite entities (like collections) are preserved.

Deserialization (Reading JSON)

Deserialization is governed by whether a member is writable. A read-only property (one without a write clause or a setter) will be skipped during deserialization.

Overriding Behavior

If you need to change how a member is treated, use these attributes:

• [NeonInclude(IncludeIf.Always)]: Forces serialization even if IgnoreReadOnlyProps is enabled. Note: This does not create a setter; the property will still be skipped during reading.
• [NeonIgnore]: Explicitly drops the member from both reading and writing.
• [NeonSetter('MethodName')]: Tells Neon to use a specific method to write the value, making the property effectively writable for deserialization.

type
  TEntity = class
  private
    FVersion: string;
  public
    procedure SetVersionValue(const AValue: string);

    [NeonSetter('SetVersionValue')]
    property Version: string read FVersion;
  end;

Neon supports most standard Delphi types, but specialized types like TGUID, TBytes, TCollection, or TDataSet require explicit registration of their serializers in the configuration.

Important: TNeonConfiguration.Default starts with an empty registry. If you do not register a serializer, Neon falls back to generic RTTI handling, which often produces incorrect results for these types.

To register serializers, use the RegisterSerializer method on your configuration object. It is recommended to use the INeonConfiguration.RegisterSerializer path to ensure the serializer's ChangeConfig hook is executed.

Example registration:

uses
  Neon.Core.Serializers.RTL,
  Neon.Core.Serializers.DB,
  Neon.Core.Serializers.VCL,
  Neon.Core.Serializers.Nullables;

LConfig := TNeonConfiguration.Default
  .RegisterSerializer(TGUIDSerializer)
  .RegisterSerializer(TBytesSerializer)
  .RegisterSerializer(TStreamSerializer)
  .RegisterSerializer(TJSONValueSerializer)
  .RegisterSerializer(TCollectionSerializer)
  .RegisterSerializer(TDataSetSerializer)
  .RegisterSerializer(TImageSerializer);

RegisterNullableSerializers(LConfig.GetSerializers);

The repository includes several demonstration projects to help you understand the library's capabilities:

• Neon Main Demo: Demonstrates serialization/deserialization of simple types, records, classes, and Delphi-specific types like TStringList and TDataSet.
• Neon Benchmarks Demo: Compares Neon's performance against other serialization engines.
• Console Demos: A collection of command-line tools for advanced usage:
  • BenchmarksConsole: Compares Neon against REST.Json and System.JSON.Serializers (TJsonSerializer).
  • ProfilingConsole: Uses TNeonLogger to profile internal stages like RTTI resolution and member preparation.
  • Classify: Converts JSON documents into Delphi entities.
  • SchemaConsole: Generates JSON Schema Draft 2020-12 from Delphi types and validates JSON against them.
  • ReadOnlyConsole: Demonstrates handling of read-only and write-only members.

Neon provides extensive configuration through the INeonConfiguration interface. You can customize how Delphi members are mapped to JSON keys, how visibility is handled, and how specific types are processed.

Key configuration options include:

• Word Case: Set the JSON key casing using options like Unchanged, UPPERCASE, lowercase, PascalCase, camelCase, snake_case, kebab-case, or SCREAMING_SNAKE_CASE.
• Member Types: Choose whether to serialize Fields, Properties, or both.
• Member Visibility: Filter by private, protected, public, or published.
• Ignore Field Prefix: An option to automatically strip the F prefix from private/protected fields (e.g., FFirstName becomes FirstName). Warning: TNeonConfiguration.Snake and .ScreamingSnake turn this on by default.
• Read-only Properties: Use SetIgnoreReadOnlyProps(True) to omit properties that only have a read clause during serialization.
• Map/Dictionary Sort Order: Control key ordering with natural, reverse, alphabetical, or reverse-alphabetical.
• Custom Serializers: Register custom logic for specific types.

Neon uses an INeonConfiguration interface (instantiated via TNeonConfiguration.Default) to define how serialization behaves. You can configure member casing, which members to include, field prefixes, visibility, and custom serializers.

Case Settings

TNeonCase affects both member names and enum names:

• TNeonCase.CamelCase: Converts Admin to "admin".
• TNeonCase.SnakeCase: Converts VeryHighSpeed to "very_high_speed".
• Note: Explicit [NeonEnumNames(...)] or [NeonProperty] attributes take precedence over these settings.

Configuration Options

• .SetMemberCase(TNeonCase): Sets the naming convention.
• .SetMembers(TNeonMembers): Defines which member types to include (e.g., TNeonMembers.Properties).
• .SetIgnoreFieldPrefix(Boolean): Handles prefixes like F (common in Delphi fields).
• .SetVisibility([TVisibility]): Controls which RTTI visibility levels are processed (e.g., mvPublic, mvPublished).
• .RegisterSerializer(TSerializer): Registers a custom serializer for specific types.

var
  LConfig: INeonConfiguration;
begin
  LConfig := TNeonConfiguration.Default
    .SetMemberCase(TNeonCase.SnakeCase)     // Case settings
    .SetMembers(TNeonMembers.Properties)    // Member type settings
    .SetIgnoreFieldPrefix(True)             // F Prefix settings
    .SetVisibility([mvPublic, mvPublished]) // Visibility settings

    // Custom serializer registration
    .RegisterSerializer(TGUIDSerializer)
  ;
end;