https://github.com/filip26/titanium-jcs
Deterministic JSON serialization and canonical equality. RFC 8785 JCS
https://github.com/filip26/titanium-jcs
canonical canonicalization canonicalize canonize equality jackson-databind jakarta-json-api jcs json
Last synced: 27 days ago
JSON representation
Deterministic JSON serialization and canonical equality. RFC 8785 JCS
- Host: GitHub
- URL: https://github.com/filip26/titanium-jcs
- Owner: filip26
- License: apache-2.0
- Created: 2025-02-20T17:43:18.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-11T22:27:35.000Z (3 months ago)
- Last Synced: 2026-03-12T03:22:25.627Z (3 months ago)
- Topics: canonical, canonicalization, canonicalize, canonize, equality, jackson-databind, jakarta-json-api, jcs, json
- Language: Java
- Homepage: https://apicatalog.com
- Size: 177 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Titanium JCS
[](https://github.com/filip26/titanium-jcs/actions/workflows/java21-build.yml)
[](https://app.codacy.com/gh/filip26/titanium-jcs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://app.codacy.com/gh/filip26/titanium-jcs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
[](https://javadoc.io/doc/com.apicatalog/titanium-jcs)
[](https://search.maven.org/search?q=g:com.apicatalog%20AND%20a:titanium-jcs)
[](https://opensource.org/licenses/Apache-2.0)
The JSON Canonicalization Scheme (JCS) defines a deterministic way to serialize JSON so that the same JSON data model always produces the same byte sequence.
This is critical for use cases such as digital signatures, hashing, and data integrity verification, where even small differences in whitespace, member ordering, or number formatting would otherwise break validation.
By normalizing JSON into a canonical form, JCS ensures interoperability across systems and guarantees stable, repeatable representations of data.
Titanium JCS is a Java implementation of the [RFC 8785 JSON Canonicalization Scheme (JCS)](https://www.rfc-editor.org/rfc/rfc8785).
> 📝 Note: Handling decimals in JSON is a known challenge, and certain corner cases may not behave as expected. JCS adheres to ECMAScript’s number handling, which can reflect these limitations with decimal values.
## ✨ Features
- **Non-recursive Canonical JSON Writer**
Deterministically serializes JSON values into a stable, repeatable form
following [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785).
- **Canonical JSON Equality Comparator**
Compares JSON values for equality under JCS rules, ensuring numbers, objects,
and arrays are compared in their canonical form rather than raw text.
- **Uniform, JSON Library-Agnostic API**
Built on a uniform [Tree I/O API](https://github.com/filip26/tree-io) for JSON data processing.
Jackson and Jakarta are supported out of the box.
## Example
```javascript
// Canonicalize a JSON value and return the canonical string
var canonicalJson = Jcs.canonize(json, adapter);
// Canonicalize a JSON value and write canonical JSON to a writer
Jcs.canonize(json, adapter, writer);
// Compare two JSON values for canonical equality
if (Jcs.equals(json1, json2, adapter)) {
// values are equal under RFC 8785 rules
}
```
## 📦 Installation
```xml
com.apicatalog
titanium-jcs
${titanium-jcs.version}
com.apicatalog
tree-io-jackson2
${tree-io.version}
com.apicatalog
tree-io-jakarta
${tree-io.version}
org.glassfish
jakarta.json
2.0.1
```
## 🛠️ LD-CLI
[LD-CLI](https://github.com/filip26/ld-cli) is a command-line utility for
working with JSON, JSON-LD, CBOR-LD, multiformats, and related specifications.
It provides encoding, decoding, detection, analysis, and format conversion
features, making it useful for inspecting identifiers, testing content
addressing, and integrating multiformats into development workflows.
### Example
Canonicalize JSON and write canonical JSON to stdout
```bash
cat test.json | ld-cli jcs
```
## 🤝 Contributing
Contributions are welcome! Please submit a pull request.
### Building
Fork and clone the repository, then build with Maven:
```bash
> cd titanium-jcs
> mvn package
```
## Resources
- [RFC 8785 JSON Canonicalization Scheme (JCS)](https://www.rfc-editor.org/rfc/rfc8785)
- [JSON Canonicalization Scheme (JCS)](https://github.com/cyberphone/json-canonicalization)
- [Tree I/O](https://github.com/filip26/tree-io)
- [Titanium RDF Canon](https://github.com/filip26/titanium-rdf-canon)
- [LD-CLI](https://github.com/filip26/ld-cli)
## 💼 Commercial Support
Commercial support and consulting are available.
For inquiries, please contact: filip26@gmail.com