UnambitiousFx.Engram
1.1.0
dotnet add package UnambitiousFx.Engram --version 1.1.0
NuGet\Install-Package UnambitiousFx.Engram -Version 1.1.0
<PackageReference Include="UnambitiousFx.Engram" Version="1.1.0" />
<PackageVersion Include="UnambitiousFx.Engram" Version="1.1.0" />
<PackageReference Include="UnambitiousFx.Engram" />
paket add UnambitiousFx.Engram --version 1.1.0
#r "nuget: UnambitiousFx.Engram, 1.1.0"
#:package UnambitiousFx.Engram@1.1.0
#addin nuget:?package=UnambitiousFx.Engram&version=1.1.0
#tool nuget:?package=UnambitiousFx.Engram&version=1.1.0
UnambitiousFx.Engram
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,net10.0, andnet11.0.
🎯 Features
- RFC 8785 canonical form of a
JsonElement, aJsonNode, a JSON text (string or UTF-8 bytes), or a typed value serialized through its source-generatedJsonTypeInfo<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.toStringdoes, as RFC 8785 requires. - Strict: duplicate member names, numbers outside the double range and lone surrogates throw a
FormatExceptioninstead 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 | Versions 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. net11.0 is compatible. |
-
net10.0
- No dependencies.
-
net11.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.