UnambitiousFx.Engram 1.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package UnambitiousFx.Engram --version 1.0.0
                    
NuGet\Install-Package UnambitiousFx.Engram -Version 1.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="UnambitiousFx.Engram" Version="1.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="UnambitiousFx.Engram" Version="1.0.0" />
                    
Directory.Packages.props
<PackageReference Include="UnambitiousFx.Engram" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add UnambitiousFx.Engram --version 1.0.0
                    
#r "nuget: UnambitiousFx.Engram, 1.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package UnambitiousFx.Engram@1.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=UnambitiousFx.Engram&version=1.0.0
                    
Install as a Cake Addin
#tool nuget:?package=UnambitiousFx.Engram&version=1.0.0
                    
Install as a Cake Tool

UnambitiousFx.Engram

Build Status NuGet codecov License: MIT .NET Documentation

RFC 8785 JSON Canonicalization Scheme (JCS) for .NET: one deterministic form for any JSON value, and a SHA-256 fingerprint of that form.

Two JSON texts can carry the same data and still differ byte for byte: member order, whitespace, number formatting (1.0 and 1, 1e3 and 1000), string escapes. Engram turns both into the same canonical text, so you can compare, hash, sign or deduplicate JSON.

An engram is the stable trace a memory leaves in the brain. Here, it is the trace a JSON document leaves: its canonical form and its fingerprint.

🔧 Compatibility & support

  • Dependency-free: only the BCL and System.Text.Json.
  • NativeAOT and trimming compatible: CI publishes and runs an AOT binary on every change.
  • Supported .NET versions: net8.0, net9.0, and net10.0.

🎯 Features

  • RFC 8785 canonical form of a JsonElement, a JsonNode, a JSON text (string or UTF-8 bytes), or a typed value serialized through its source-generated JsonTypeInfo<T>.
  • Content fingerprint: the lowercase hex SHA-256 of the UTF-8 canonical form.
  • ECMAScript number formatting: the shortest digits that round-trip, laid out as Number.prototype.toString does, as RFC 8785 requires.
  • Strict: duplicate member names, numbers outside the double range and lone surrogates throw a FormatException instead of producing a form another implementation would not reproduce.
  • Tested against the reference vectors of the RFC (Appendix B) and of its reference implementation.

📦 Installation

dotnet add package UnambitiousFx.Engram

🚀 Quick start

using UnambitiousFx.Engram;

var a = """{ "currency": "EUR", "amount": 12.50 }""";
var b = """{"amount":12.5,"currency":"EUR"}""";

JsonCanonicalizer.Canonicalize(a);   // {"amount":12.5,"currency":"EUR"}
JsonCanonicalizer.Hash(a) == JsonCanonicalizer.Hash(b);   // true

// the bytes to sign or HMAC
byte[] payload = JsonCanonicalizer.CanonicalizeToUtf8(a);

// a typed value, through its source-generated metadata (no reflection)
string fingerprint = JsonCanonicalizer.Hash(order, AppJsonContext.Default.Order);

💡 Use cases

Need How
Idempotency, deduplication Store Hash(payload); a second submission of the same data has the same fingerprint.
Change detection Compare the fingerprint of the new export with the last one, without keeping the old document.
Signatures Sign CanonicalizeToUtf8(value); a verifier that re-serializes the JSON still checks the same bytes.
ETags Use the fingerprint of the response body instead of a timestamp.

📚 API

Method Returns
Canonicalize(…) The canonical JSON text.
CanonicalizeToUtf8(…) The canonical JSON text as UTF-8 bytes, without a byte order mark.
Hash(…) The lowercase hex SHA-256 of the UTF-8 canonical form (64 characters).
FormatNumber(double) A number as it appears in a canonical text.

Each of the first three accepts a JsonElement, a JSON string, UTF-8 bytes (ReadOnlySpan<byte>), a JsonNode? (null is JSON null), or a value with its JsonTypeInfo<T>.

🤝 Contributing

See CONTRIBUTING.md.

📄 License

MIT. The test vectors under test/Engram.Tests/vectors/official come from the RFC 8785 reference implementation under the Apache License 2.0.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.
  • net8.0

    • No dependencies.
  • net9.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 4,919 11/11/2026
1.0.0 1,176 11/10/2026