com.apicatalog.jcs

Class Jcs

java.lang.Object

com.apicatalog.jcs.Jcs

public final class Jcs
extends Object

An implementation of the RFC 8785 JSON Canonicalization Scheme (JCS) specification in Java.

This class provides two main capabilities:

• Canonicalization – serializing JSON values into a deterministic and standardized form, ensuring that the same JSON data model always produces the same byte sequence.
• Equality comparison – comparing JSON values for canonical equality, i.e., equality after applying JCS rules for numbers, arrays, and objects.

This implementation uses Jakarta JSON Processing (JSON-P) as input and can output canonicalized JSON to a Writer or return it as a String.

Usage examples:

 // Canonicalize a JSON value and write to a writer
 Jcs.canonize(jsonValue, writer);

 // Compare two JSON values for canonical equality
 boolean equal = Jcs.equals(json1, json2);
 

Field Summary

Fields

Modifier and Type	Field and Description
protected static DecimalFormat	eFormat Plain notation used by JCS for mid-range BigDecimal values (English locale).
protected static DecimalFormat	eFormatBigDecimal Exponent notation used by JCS for very large/small BigDecimal values (English locale).

Constructor Summary

Constructors

Constructor and Description
Jcs()

Method Summary

Modifier and Type	Method and Description
static boolean	arrayEquals(jakarta.json.JsonArray array1, jakarta.json.JsonArray array2) Compares two JSON arrays for canonical equality under RFC 8785 (JCS).
static String	canonize(jakarta.json.JsonValue value) Canonicalizes a JSON value according to the RFC 8785 JSON Canonicalization Scheme (JCS) and returns the canonicalized JSON as a string.
static void	canonize(jakarta.json.JsonValue value, Writer writer) Canonicalizes a JSON according to the RFC 8785 JSON Canonicalization Scheme (JCS).
static void	canonizeArray(jakarta.json.JsonArray value, Writer writer) Canonicalizes a JSON array according to the RFC 8785 JSON Canonicalization Scheme (JCS).
static String	canonizeNumber(jakarta.json.JsonNumber number) Canonicalizes a JSON number according to the RFC 8785 JSON Canonicalization Scheme (JCS).
static void	canonizeObject(jakarta.json.JsonObject value, Writer writer) Canonicalizes a JSON object according to the RFC 8785 JSON Canonicalization Scheme (JCS).
static boolean	equals(jakarta.json.JsonValue value1, jakarta.json.JsonValue value2) Compares two JSON values for canonical equality under RFC 8785 (JCS).
static String	escape(String value) Escapes special characters in a JSON property name according to JSON canonicalization rules.
static boolean	numberEquals(jakarta.json.JsonNumber number1, jakarta.json.JsonNumber number2) Compares two JSON numbers for canonical equality under RFC 8785 (JCS).
static boolean	objectEquals(jakarta.json.JsonObject object1, jakarta.json.JsonObject object2) Compares two JSON objects for canonical equality under RFC 8785 (JCS).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

eFormatBigDecimal

protected static final DecimalFormat eFormatBigDecimal

Exponent notation used by JCS for very large/small BigDecimal values (English locale).

eFormat

protected static final DecimalFormat eFormat

Plain notation used by JCS for mid-range BigDecimal values (English locale).

Constructor Detail

Jcs

public Jcs()

Method Detail

canonize

public static final String canonize(jakarta.json.JsonValue value)

Canonicalizes a JSON value according to the RFC 8785 JSON Canonicalization Scheme (JCS) and returns the canonicalized JSON as a string.

This method serializes the given JsonValue in a deterministic and standardized manner, ensuring a consistent output regardless of formatting differences. It handles all JSON value types, including objects, arrays, numbers, strings, and literals (true, false, null).

Parameters:

value - the JSON value to be canonicalized

Returns:

a string containing the canonicalized JSON representation of the input value

canonize

public static final void canonize(jakarta.json.JsonValue value,
                                  Writer writer)
                           throws IOException

Canonicalizes a JSON according to the RFC 8785 JSON Canonicalization Scheme (JCS).

This method serializes the given JsonValue in a deterministic and standardized manner, ensuring a consistent output regardless of formatting differences. The canonicalized JSON is written to the provided Writer.

This method handles different JSON value types, including objects, arrays, numbers, strings, and literals (true, false, null).

Parameters:

value - the JSON value to be canonicalized

writer - the writer to which the canonicalized JSON output is written

Throws:

IOException - if an I/O error occurs while writing to the writer

canonizeNumber

public static final String canonizeNumber(jakarta.json.JsonNumber number)

Canonicalizes a JSON number according to the RFC 8785 JSON Canonicalization Scheme (JCS).

This method serializes the given JsonNumber in a deterministic and standardized manner, ensuring a consistent numeric representation.

Parameters:

number - the JSON number to be canonicalized

Returns:

the canonicalized representation

canonizeArray

public static final void canonizeArray(jakarta.json.JsonArray value,
                                       Writer writer)
                                throws IOException

Canonicalizes a JSON array according to the RFC 8785 JSON Canonicalization Scheme (JCS).

This method serializes the given JsonArray in a deterministic and standardized manner, ensuring a consistent output. The canonicalized JSON array is written to the provided Writer.

Parameters:

value - the JSON array to be canonicalized

writer - the writer to which the canonicalized JSON output is written

Throws:

IOException - if an I/O error occurs while writing to the writer

canonizeObject

public static final void canonizeObject(jakarta.json.JsonObject value,
                                        Writer writer)
                                 throws IOException

Canonicalizes a JSON object according to the RFC 8785 JSON Canonicalization Scheme (JCS).

This method serializes the given JsonObject in a deterministic and standardized manner, ensuring a consistent output. The canonicalized JSON is written to the provided Writer.

Parameters:

value - the JSON object to be canonicalized

writer - the writer to which the canonicalized JSON output is written

Throws:

IOException - if an I/O error occurs while writing to the writer

escape

public static final String escape(String value)

Escapes special characters in a JSON property name according to JSON canonicalization rules.

This method ensures that control characters and other necessary characters are properly escaped to maintain a valid and consistent JSON representation.

Parameters:

value - the JSON property name to escape

Returns:

the escaped property name

equals

public static final boolean equals(jakarta.json.JsonValue value1,
                                   jakarta.json.JsonValue value2)

Compares two JSON values for canonical equality under RFC 8785 (JCS).

Values are considered equal if their JSON data models are the same after applying JCS canonicalization rules. That includes canonical number formatting and lexicographic member ordering for objects.

Parameters:

value1 - the first JSON value (may be null)

value2 - the second JSON value (may be null)

Returns:

true if the two values are canonically equal; false otherwise

numberEquals

public static final boolean numberEquals(jakarta.json.JsonNumber number1,
                                         jakarta.json.JsonNumber number2)

Compares two JSON numbers for canonical equality under RFC 8785 (JCS).

The comparison is performed by canonicalizing each number using canonizeNumber(JsonNumber) and comparing the resulting strings.

Parameters:

number1 - the first JSON number

number2 - the second JSON number

Returns:

true if both numbers have the same canonical representation; false otherwise

objectEquals

public static final boolean objectEquals(jakarta.json.JsonObject object1,
                                         jakarta.json.JsonObject object2)

Compares two JSON objects for canonical equality under RFC 8785 (JCS).

Objects are equal if they contain the same set of member names (after escaping per JCS) and corresponding member values are canonically equal as determined by equals(JsonValue, JsonValue).

Parameters:

object1 - the first JSON object

object2 - the second JSON object

Returns:

true if the two objects are canonically equal; false otherwise

arrayEquals

public static final boolean arrayEquals(jakarta.json.JsonArray array1,
                                        jakarta.json.JsonArray array2)

Compares two JSON arrays for canonical equality under RFC 8785 (JCS).

Arrays are equal if they have the same length and each element at position i is canonically equal as determined by equals(JsonValue, JsonValue).

Parameters:

array1 - the first JSON array

array2 - the second JSON array

Returns:

true if the two arrays are canonically equal; false otherwise