Package com.apicatalog.jcs

Class Jcs

  • public final class Jcs
extends java.lang.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 Description
      protected static java.text.DecimalFormat eFormat
      Plain notation used by JCS for mid-range BigDecimal values (English locale).
      protected static java.text.DecimalFormat eFormatBigDecimal
      Exponent notation used by JCS for very large/small BigDecimal values (English locale).

    • Constructor Summary

      Constructors 
      Constructor Description
      Jcs()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean arrayEquals​(jakarta.json.JsonArray array1, jakarta.json.JsonArray array2)
      Compares two JSON arrays for canonical equality under RFC 8785 (JCS).
      static java.lang.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, java.io.Writer writer)
      Canonicalizes a JSON according to the RFC 8785 JSON Canonicalization Scheme (JCS).
      static void canonizeArray​(jakarta.json.JsonArray value, java.io.Writer writer)
      Canonicalizes a JSON array according to the RFC 8785 JSON Canonicalization Scheme (JCS).
      static java.lang.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, java.io.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 java.lang.String escape​(java.lang.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 java.text.DecimalFormat eFormatBigDecimal
        Exponent notation used by JCS for very large/small BigDecimal values (English locale).

      • eFormat

        protected static final java.text.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 java.lang.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,
                                  java.io.Writer writer)
                           throws java.io.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:
        java.io.IOException - if an I/O error occurs while writing to the writer

      • canonizeNumber

        public static final java.lang.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,
                                       java.io.Writer writer)
                                throws java.io.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:
        java.io.IOException - if an I/O error occurs while writing to the writer

      • canonizeObject

        public static final void canonizeObject​(jakarta.json.JsonObject value,
                                        java.io.Writer writer)
                                 throws java.io.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:
        java.io.IOException - if an I/O error occurs while writing to the writer

      • escape

        public static final java.lang.String escape​(java.lang.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