# cyberphone/json-canonicalization architecture

> Architecture diagram of the GitHub repository cyberphone/json-canonicalization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyberphone/json-canonicalization
- Repository: https://github.com/cyberphone/json-canonicalization

## Overview

##### Main Components
- Core Canonicalization Algorithm: At the heart of the project is the logic which, according to the JCS standard, serializes JSON primitives and sorts JSON object properties lexicographically (while leaving arrays in their original order). This algorithm gets implemented multiple times (one per language) with slight differences for language idioms.
- Multi-language Implementations:
- .NET (dotnet): Contains several projects like “es6numberserializer”, “json.net.sign”, “jsoncanonicalizer”, “verify-canonicalization”, and “verify-numbers.” These projects cover both the canonicalization process and testing/verification of numbers and signatures.
- Go: Has its own core implementation and tests under directories such as “go/src/webpki.org/jsoncanonicalizer” and “go/test.”
- Java: Has separate modules – one for canonicalization and an older “deprecated” set for reference. Also, an additional miscellaneous module provides extra utilities or examples.
- Node.js (node-es6): Contains simple JavaScript scripts (like canonicalize.js) that implement the canonicalization and verification scripts.
- Python3: Provides the canonicalization logic under “python3/src/org/webpki/json” and its corresponding tests.
- Testing/Verification Components:
- The “testdata” directory holds sample JSON input and pre-canonicalized outputs.
- Each language implementation includes separate test scripts (e.g., “verify-canonicalization” and “verify-numbers” for .NET and Go, and similar for Python) that confirm the correctness of the canonicalization.
- Browser Demo:
- The “browsers” directory contains an HTML file used to test the canonicalization in-browser.

##### Relationships and Interactions
- Each language-specific module acts as an independent “service” or “library component” that exposes an API (or command-line tool) to perform JSON canonicalization.
- The testing components feed input into the canonicalization components and compare output against expected results (often provided in the “testdata” folder).
- In the .NET branch, for example, components like “es6numberserializer” and “json.net.sign” might interact where signing functionality leverages the canonicalizer’s output.
- Even though implementations are separate, they share the same conceptual design: receive JSON input → apply ECMAScript-compatible serialization rules → perform lexicographic property sorting → output UTF-8 canonicalized JSON.

##### Architectural Patterns and Design Principles
- Modularity: The project is clearly segmented by language, with each path maintaining its own build system and project structure. This makes each a self-contained module that can be maintained and extended separately.
- Cross-Platform Consistency: Although the implementation details might differ (e.g., C# vs. Go vs. Java), all modules conform to the same canonicalization rules defined by JCS.
- Testing/Verification: The project emphasizes verification by including multiple test harnesses and sample data to verify both canonicalization and number serialization fidelity.
- Extensibility: The separation of concerns (canonicalization algorithm, number conversion, signature support) hints at an architecture designed to allow each part to be updated or replaced independently.

##### Relevant Technologies, Frameworks, or Libraries
- The .NET implementation uses C# and standard .NET project files (.csproj, solution files).
- The Java implementation uses Ant for building (build.xml) and jars for distribution.
- The Go implementation follows standard Go conventions with src and test directories.
- JavaScript and Python implementations use their respective standard libraries.
- The build and test tools are language-specific, but the overall design doesn’t show a centralized middleware or API gateway since each module is a standalone library.

##### Elements
- Clear Labels: For each major component (e.g., “.NET Implementation” with its submodules, “Go Implementation”, “Java Implementation”, “JavaScript Implementation”, “Python Implementation”, “Test Data & Verification”, “Browser Demo”).
- Implementation layers (core algorithm modules vs. testing/verification modules)
- Language-specific modules
- Utility/demo components (browser test, test data)
- Annotations to note that while each implementation is built independently, they all conform to the same RFC (RFC8785) and JCS principles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["JSON Canonicalization (JCS)"]:::header
    B(("Test Data")):::data
    C["Canonical JSON Output"]:::output

    %% .NET Implementation Subgraph
    subgraph ".NET Implementation"
        netCore["Core Canonicalization (.NET)"]:::dotnet
        netNumSer["Number Serialization Module (.NET)"]:::dotnet
        netSign["Signature & Signing Support (.NET)"]:::dotnet
        netVerifyCanon["Test: Verify Canonicalization (.NET)"]:::dotnetTest
        netVerifyNumbers["Test: Verify Numbers (.NET)"]:::dotnetTest
    end

    %% Go Implementation Subgraph
    subgraph "Go Implementation"
        goCore["Go Canonicalizer Core"]:::go
        goTests["Go Tests"]:::goTest
    end

    %% Java Implementation Subgraph
    subgraph "Java Implementation"
        javaCanon["Java Canonicalizer Module"]:::java
        javaDeprecated["Deprecated Number Serialization (Java)"]:::java
        javaMisc["Miscellaneous Utilities/Examples (Java)"]:::java
    end

    %% Node.js Implementation Subgraph
    subgraph "Node.js Implementation"
        nodeCore["Node.js Canonicalization Core"]:::node
        nodeVerifyCanon["Test: Verify Canonicalization (Node.js)"]:::nodeTest
        nodeVerifyNumbers["Test: Verify Numbers (Node.js)"]:::nodeTest
    end

    %% Python3 Implementation Subgraph
    subgraph "Python3 Implementation"
        pythonCore["Python3 Canonicalization Core"]:::python
        pythonNumConv["Number Conversion (Python3)"]:::python
        pythonTests["Python3 Tests"]:::pythonTest
    end

    %% Browser Demo Component
    browserDemo["Browser Demo"]:::demo

    %% Connections from Header to Test Data
    A --> B

    %% Connections from Test Data to each Core Implementation
    B --> netCore
    B --> goCore
    B --> javaCanon
    B --> nodeCore
    B --> pythonCore
    B --> browserDemo

    %% Internal .NET Connections
    netCore -->|"uses"| netSign
    netCore -->|"feeds"| netVerifyCanon
    netCore -->|"feeds"| netVerifyNumbers
    netNumSer --- netCore

    %% Go internal test connection
    goCore -->|"validatedBy"| goTests

    %% Node.js internal test connections
    nodeCore -->|"validatedBy"| nodeVerifyCanon
    nodeCore -->|"validatedBy"| nodeVerifyNumbers

    %% Python internal test connections
    pythonCore -->|"validatedBy"| pythonTests
    pythonCore -->|"supportedBy"| pythonNumConv

    %% All Core Implementations send output to Canonical JSON Output
    netCore --> C
    goCore --> C
    javaCanon --> C
    nodeCore --> C
    pythonCore --> C
    browserDemo --> C

    %% Click Events
    click netCore "https://github.com/cyberphone/json-canonicalization/blob/master/dotnet/jsoncanonicalizer/JsonCanonicalizer.cs"
    click netNumSer "https://github.com/cyberphone/json-canonicalization/tree/master/dotnet/es6numberserializer/"
    click netSign "https://github.com/cyberphone/json-canonicalization/tree/master/dotnet/json.net.sign/"
    click netVerifyCanon "https://github.com/cyberphone/json-canonicalization/tree/master/dotnet/verify-canonicalization/"
    click netVerifyNumbers "https://github.com/cyberphone/json-canonicalization/tree/master/dotnet/verify-numbers/"
    click goCore "https://github.com/cyberphone/json-canonicalization/tree/master/go/src/webpki.org/jsoncanonicalizer/"
    click goTests "https://github.com/cyberphone/json-canonicalization/tree/master/go/test/"
    click javaCanon "https://github.com/cyberphone/json-canonicalization/tree/master/java/canonicalizer/"
    click javaDeprecated "https://github.com/cyberphone/json-canonicalization/tree/master/java/deprecated/"
    click javaMisc "https://github.com/cyberphone/json-canonicalization/tree/master/java/miscellaneous/"
    click nodeCore "https://github.com/cyberphone/json-canonicalization/blob/master/node-es6/canonicalize.js"
    click nodeVerifyCanon "https://github.com/cyberphone/json-canonicalization/blob/master/node-es6/verify-canonicalization.js"
    click nodeVerifyNumbers "https://github.com/cyberphone/json-canonicalization/blob/master/node-es6/verify-numbers.js"
    click pythonCore "https://github.com/cyberphone/json-canonicalization/blob/master/python3/src/org/webpki/json/Canonicalize.py"
    click pythonNumConv "https://github.com/cyberphone/json-canonicalization/blob/master/python3/src/org/webpki/json/NumberToJson.py"
    click pythonTests "https://github.com/cyberphone/json-canonicalization/tree/master/python3/test/"
    click browserDemo "https://github.com/cyberphone/json-canonicalization/blob/master/browsers/browser-json-canonicalization.html"
    click B "https://github.com/cyberphone/json-canonicalization/tree/master/testdata/"

    %% Styles
    classDef header fill:#D1E8FF,stroke:#0B5394,stroke-width:2px;
    classDef data fill:#FFF2CC,stroke:#BF9000,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef output fill:#C9F7C5,stroke:#28A745,stroke-width:2px;
    classDef dotnet fill:#CCE5FF,stroke:#1C4587,stroke-width:2px;
    classDef dotnetTest fill:#EBF1DE,stroke:#3C8031,stroke-width:2px;
    classDef go fill:#D1F2EB,stroke:#0E6251,stroke-width:2px;
    classDef goTest fill:#E8F8F5,stroke:#117864,stroke-width:2px;
    classDef java fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef node fill:#FFE5B4,stroke:#D35400,stroke-width:2px;
    classDef nodeTest fill:#FDEBD0,stroke:#BA4A00,stroke-width:2px;
    classDef python fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;
    classDef pythonTest fill:#F4ECF7,stroke:#884EA0,stroke-width:2px;
    classDef demo fill:#D6DBDF,stroke:#566573,stroke-width:2px;
```
