1. Licensing and Copyright

Technology Compatibility Kit User’s Guide for Jakarta JSON Binding

Release 3.1 for Jakarta EE

March 2022

Technology Compatibility Kit User’s Guide for Jakarta JSON Binding, Release 3.1 for Jakarta EE

Copyright © 2017, 2026 Oracle and/or its affiliates. All rights reserved.

This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0, which is available at http://www.eclipse.org/legal/epl-2.0.

SPDX-License-Identifier: EPL-2.0

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

2. Preface

This guide describes how to install, configure, and run the Technology Compatibility Kit (TCK) that is used to test the Jakarta JSON Binding (JSON Binding 3.1) technology.

The JSON Binding TCK is a portable, configurable automated test suite for verifying the compatibility of a vendor’s implementation of the JSON Binding 3.1 Specification (hereafter referred to as the vendor implementation or VI). The JSON Binding TCK uses the Junit framework to run the test suite

Note

Note All references to specific Web URLs are given for the sake of your convenience in locating the resources quickly. These references are always subject to changes that are in many cases beyond the control of the authors of this guide.

Jakarta EE is a community sponsored and community run program. Organizations contribute, along side individual contributors who use, evolve and assist others. Commercial support is not available through the Eclipse Foundation resources. Please refer to the Eclipse EE4J project site (https://projects.eclipse.org/projects/ee4j). There, you will find additional details as well as a list of all the associated sub-projects (Implementations and APIs), that make up Jakarta EE and define these specifications. If you have questions about this Specification you may send inquiries to jsonb-dev@eclipse.org. If you have questions about this TCK, you may send inquiries to jsonb-dev@eclipse.org.

2.1. Who Should Use This Book

This guide is for vendors that implement the JSON Binding 3.1 technology to assist them in running the test suite that verifies compatibility of their implementation of the JSON Binding 3.1 Specification.

2.2. Before You Read This Book

You should be familiar with the JSON Binding 3.1, version 3.1 Specification, which can be found at https://jakarta.ee/specifications/jsonb/.

2.3. Typographic Conventions

The following table describes the typographic conventions that are used in this book.

Convention Meaning Example

Boldface

Boldface type indicates graphical user interface elements associated with an action, terms defined in text, or what you type, contrasted with onscreen computer output.

From the File menu, select Open Project.

A cache is a copy that is stored locally.

machine_name% su
Password:

Monospace

Monospace type indicates the names of files and directories, commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Edit your .login file.

Use ls -a to list all files.

machine_name% you have mail.

Italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

Read Chapter 6 in the User’s Guide.

Do not save the file.

The command to remove a file is rm filename.

2.4. Shell Prompts in Command Examples

The following table shows the default UNIX system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.

Shell Prompt

C shell

machine_name%

C shell for superuser

machine_name#

Bourne shell and Korn shell

$

Bourne shell and Korn shell for superuser

#

Bash shell

shell_name-shell_version$

Bash shell for superuser

shell_name-shell_version#

3. Introduction

This chapter provides an overview of the principles that apply generally to all Technology Compatibility Kits (TCKs) and describes the Jakarta JSON Binding TCK (JSON Binding 3.1 TCK). It also includes a high level listing of what is needed to get up and running with the JSON Binding TCK.

This chapter includes the following topics:

3.1. Compatibility Testing

Compatibility testing differs from traditional product testing in a number of ways. The focus of compatibility testing is to test those features and areas of an implementation that are likely to differ across other implementations, such as those features that:

  • Rely on hardware or operating system-specific behavior

  • Are difficult to port

  • Mask or abstract hardware or operating system behavior

Compatibility test development for a given feature relies on a complete specification and compatible implementation (CI) for that feature. Compatibility testing is not primarily concerned with robustness, performance, nor ease of use.

3.1.1. Why Compatibility Testing is Important

Jakarta platform compatibility is important to different groups involved with Jakarta technologies for different reasons:

  • Compatibility testing ensures that the Jakarta platform does not become fragmented as it is ported to different operating systems and hardware environments.

  • Compatibility testing benefits developers working in the Jakarta programming language, allowing them to write applications once and then to deploy them across heterogeneous computing environments without porting.

  • Compatibility testing allows application users to obtain applications from disparate sources and deploy them with confidence.

  • Conformance testing benefits Jakarta platform implementors by ensuring a level playing field for all Jakarta platform ports.

3.1.2. TCK Compatibility Rules

Compatibility criteria for all technology implementations are embodied in the TCK Compatibility Rules that apply to a specified technology. Each TCK tests for adherence to these Rules as described in Procedure for Certification

3.1.3. TCK Overview

A TCK is a set of tools and tests used to verify that a vendor’s compatible implementation of a Jakarta EE technology conforms to the applicable specification. All tests in the TCK are based on the written specifications for the Jakarta EE platform. A TCK tests compatibility of a vendor’s compatible implementation of the technology to the applicable specification of the technology. Compatibility testing is a means of ensuring correctness, completeness, and consistency across all implementations developed by technology licensees.

The set of tests included with each TCK is called the test suite. Most tests in a TCK’s test suite are self-checking, but some tests may require tester interaction. Most tests return either a Pass or Fail status. For a given platform to be certified, all of the required tests must pass. The definition of required tests may change from platform to platform.

The definition of required tests will change over time. Before your final certification test pass, be sure to download the latest version of this TCK.

3.1.4. Jakarta EE Specification Process (JESP) Program and Compatibility Testing

The Jakarta EE Specification Process (JESP) program is the formalization of the open process that has been used since 2019 to develop and revise Jakarta EE technology specifications in cooperation with the international Jakarta EE community. The JESP program specifies that the following three major components must be included as deliverables in a final Jakarta EE technology release under the direction of the responsible Expert Group:

  • Technology Specification

  • Compatible Implementation (CI)

  • Technology Compatibility Kit (TCK)

For further information about the JESP program, go to Jakarta EE Specification Process community page https://jakarta.ee/specifications.

3.2. About the TCK

The JSON Binding TCK 3.1 is designed as a portable, configurable, automated test suite for verifying the compatibility of a vendor’s implementation of the JSON Binding 3.1 Specification.

3.2.1. TCK Specifications and Requirements

This section lists the applicable requirements and specifications.

  • Specification Requirements: Software requirements for a JSON Binding implementation are described in detail in the JSON Binding 3.1 Specification. Links to the JSON Binding specification and other product information can be found at https://jakarta.ee/specifications/jsonb/.

  • JSON Binding Version: The JSON Binding 3.1 TCK is based on the JSON Binding Specification, Version 3.1.

  • Compatible Implementation: One JSON Binding 3.1 Compatible Implementation, Eclipse Yasson 3.1 is available from the Eclipse EE4J project (https://projects.eclipse.org/projects/ee4j). See the CI documentation page at https://projects.eclipse.org/projects/ee4j.yasson for more information.

See the JSON Binding TCK Release Notes for more specific information about Java SE version requirements, supported platforms, restrictions, and so on.

3.2.2. TCK Components

The JSON Binding TCK 3.1 includes the following components:

  • JSON Binding TCK signature tests; check that all public APIs are supported and/or defined as specified in the JSON Binding Version 3.1 implementation under test.

  • If applicable, an exclude list, which provides a list of tests that your implementation is not required to pass.

  • API tests for all of the JSON Binding API in all related packages:

    • jakarta.json.bind

    • jakarta.json.bind.adapter

    • jakarta.json.bind.annotation

    • jakarta.json.bind.config

    • jakarta.json.bind.serializer

    • jakarta.json.bind.spi

The JSON Binding TCK tests run on the following platforms:

  • CentOS Linux 7

3.2.3. TCK Compatibility Test Suite

The test suite is the collection of tests to test a particular technology implementation. In this case, it is the collection of tests used by the JSON Binding TCK 3.1 to test a JSON Binding 3.1 implementation. The tests are designed to verify that a vendor’s runtime implementation of the technology complies with the appropriate specification. The individual tests correspond to assertions of the specification.

The tests that make up the TCK compatibility test suite are precompiled and indexed within the TCK test directory structure.

3.2.4. Exclude Lists

Each version of a TCK includes an Exclude List contained in a TCK-Exclude-List.txt file. This is a list of test file URLs that identify tests which do not have to be run for the specific version of the TCK being used. Whenever tests are run, the Junit framework automatically excludes these tests from being executed as those are disabled using '@Ignore' tag in JUnit.

A vendor’s compatible implementation is not required to pass or run any test on the Exclude List. The Exclude List file, {excludeListFileName}, is documented in the JSON Binding TCK. Please note this file is not parsed to exclude any test and is only for documentation purpose.

Note

From time to time, updates to the Exclude List are made available. The exclude list is included in the TCK ZIP archive. Each time an update is approved and released, the version number will be incremented. You should always make sure you are using an up-to-date copy of the Exclude List before running the JSON Binding TCK to verify your implementation.

A test might be in the Exclude List for reasons such as:

  • An error in an underlying implementation API has been discovered which does not allow the test to execute properly.

  • An error in the specification that was used as the basis of the test has been discovered.

  • An error in the test itself has been discovered.

  • The test fails due to a bug in the tools used to run the test.

In addition, all tests are run against the compatible implementations. Any tests that fail when run on a compatible Jakarta platform are put on the Exclude List. Any test that is not specification-based, or for which the specification is vague, may be excluded. Any test that is found to be implementation dependent (based on a particular thread scheduling model, based on a particular file system behavior, and so on) may be excluded.

Note

Vendors are not permitted to alter or modify Exclude Lists. Changes to an Exclude List can only be made by using the procedure described in TCK Test Appeals Steps.

3.2.5. TCK Configuration

You need to set several variables in your test environment, and run the JSON Binding tests, as described in Setup and Configuration.

Note

The Jakarta EE Specification Process support multiple compatible implementations. These instructions explain how to get started with the Eclipse Yasson 3.1 CI. If you are using another compatible implementation, refer to material provided by that implementation for specific instructions and procedures.

3.3. Getting Started With the TCK

This section provides an general overview of what needs to be done to install, set up, test, and use the JSON Binding TCK. These steps are explained in more detail in subsequent chapters of this guide.

  1. Make sure that the following software has been correctly installed on the system:

    • Java SE 17+

    • A CI for JSON Binding 3.1. One example is Eclipse Yasson 3.1.

    • JSON Binding TCK version 3.1, which includes:

    • The JSON Binding 3.1 Vendor Implementation (VI)

    • Any Jupiter API compatible test runner

    See the documentation for each of these software applications for installation instructions. See Installation, for instructions on installing the JSON Binding TCK.

  2. Set up the JSON Binding TCK software.
    See Setup and Configuration, for details about the following steps.

    1. Set up your shell environment.

  3. Test the JSON Binding 3.1 implementation.
    Test the JSON Binding implementation installation by running the test suite. See Executing Tests.

4. Procedure for Certification

This chapter describes the compatibility testing procedure and compatibility requirements for Jakarta JSON Binding. This chapter contains the following sections:

4.1. Certification Overview

The certification process for JSON Binding 3.1 consists of the following activities:

  • Install the appropriate version of the Technology Compatibility Kit (TCK) and execute it in accordance with the instructions in this User’s Guide.

  • Ensure that you meet the requirements outlined in Compatibility Requirements below.

  • Certify to the Eclipse Foundation that you have finished testing and that you meet all of the compatibility requirements, as required by the Eclipse Foundation TCK License.

4.2. Compatibility Requirements

The compatibility requirements for JSON Binding 3.1 consist of meeting the requirements set forth by the rules and associated definitions contained in this section.

4.2.1. Definitions

These definitions are for use only with these compatibility requirements and are not intended for any other purpose.

Table 1. Definitions
Term Definition

API Definition Product

A Product for which the only Java class files contained in the product are those corresponding to the application programming interfaces defined by the Specifications, and which is intended only as a means for formally specifying the application programming interfaces defined by the Specifications.

Computational Resource

A piece of hardware or software that may vary in quantity, existence, or version, which may be required to exist in a minimum quantity and/or at a specific or minimum revision level so as to satisfy the requirements of the Test Suite.

Examples of computational resources that may vary in quantity are RAM and file descriptors.

Examples of computational resources that may vary in existence (that is, may or may not exist) are graphics cards and device drivers.

Examples of computational resources that may vary in version are operating systems and device drivers.

Configuration Descriptor

Any file whose format is well defined by a specification and which contains configuration information for a set of Java classes, archive, or other feature defined in the specification.

Conformance Tests

All tests in the Test Suite for an indicated Technology Under Test, as released and distributed by the Eclipse Foundation, excluding those tests on the published Exclude List for the Technology Under Test.

Container

An implementation of the associated Libraries, as specified in the Specifications, and a version of a Java Platform, Standard Edition Runtime Product, as specified in the Specifications, or a later version of a Java Platform, Standard Edition Runtime Product that also meets these compatibility requirements.

Documented

Made technically accessible and made known to users, typically by means such as marketing materials, product documentation, usage messages, or developer support programs.

Exclude List

The most current list of tests, released and distributed by the Eclipse Foundation, that are not required to be passed to certify conformance. The Jakarta EE Specification Committee may add to the Exclude List for that Test Suite as needed at any time, in which case the updated TCK version supplants any previous Exclude Lists for that Test Suite.

Libraries

The class libraries, as specified through the Jakarta EE Specification Process (JESP), for the Technology Under Test.

The Libraries for Jakarta JSON Binding are listed at the end of this chapter.

Location Resource

A location of classes or native libraries that are components of the test tools or tests, such that these classes or libraries may be required to exist in a certain location in order to satisfy the requirements of the test suite.

For example, classes may be required to exist in directories named in a CLASSPATH variable, or native libraries may be required to exist in directories named in a PATH variable.

Maintenance Lead

The corresponding Jakarta EE Specification Project is responsible for maintaining the Specification, and the TCK for the Technology. The Specification Project Team will propose revisions and updates to the Jakarta EE Specification Committee which will approve and release new versions of the specification and TCK.

Operating Mode

Any Documented option of a Product that can be changed by a user in order to modify the behavior of the Product.

For example, an Operating Mode can be binary (enable/disable optimization), an enumeration (select from a list of protocols), or a range (set the maximum number of active threads).

Note that an Operating Mode may be selected by a command line switch, an environment variable, a GUI user interface element, a configuration or control file, etc.

Product

A vendor’s product in which the Technology Under Test is implemented or incorporated, and that is subject to compatibility testing.

Product Configuration

A specific setting or instantiation of an Operating Mode.

For example, a Product supporting an Operating Mode that permits user selection of an external encryption package may have a Product Configuration that links the Product to that encryption package.

Rebuildable Tests

Tests that must be built using an implementation-specific mechanism. This mechanism must produce specification-defined artifacts. Rebuilding and running these tests against a known compatible implementation verifies that the mechanism generates compatible artifacts.

Resource

A Computational Resource, a Location Resource, or a Security Resource.

Rules

These definitions and rules in this Compatibility Requirements section of this User’s Guide.

Runtime

The Containers specified in the Specifications.

Security Resource

A security privilege or policy necessary for the proper execution of the Test Suite.

For example, the user executing the Test Suite will need the privilege to access the files and network resources necessary for use of the Product.

Specifications

The documents produced through the Jakarta EE Specification Process (JESP) that define a particular Version of a Technology.

The Specifications for the Technology Under Test are referenced later in this chapter.

Technology

Specifications and one or more compatible implementations produced through the Jakarta EE Specification Process (JESP).

Technology Under Test

Specifications and a compatible implementation for Jakarta JSON Binding Version 3.1.

Test Suite

The requirements, tests, and testing tools distributed by the Maintenance Lead as applicable to a given Version of the Technology.

Version

A release of the Technology, as produced through the Jakarta EE Specification Process (JESP).

4.2.2. Rules for Jakarta JSON Binding Products

The following rules apply for each version of an operating system, software component, and hardware platform Documented as supporting the Product:

JSONB1 The Product must be able to satisfy all applicable compatibility requirements, including passing all Conformance Tests, in every Product Configuration and in every combination of Product Configurations, except only as specifically exempted by these Rules.

For example, if a Product provides distinct Operating Modes to optimize performance, then that Product must satisfy all applicable compatibility requirements for a Product in each Product Configuration, and combination of Product Configurations, of those Operating Modes.

JSONB1.1 If an Operating Mode controls a Resource necessary for the basic execution of the Test Suite, testing may always use a Product Configuration of that Operating Mode providing that Resource, even if other Product Configurations do not provide that Resource. Notwithstanding such exceptions, each Product must have at least one set of Product Configurations of such Operating Modes that is able to pass all the Conformance Tests.

For example, a Product with an Operating Mode that controls a security policy (i.e., Security Resource) which has one or more Product Configurations that cause Conformance Tests to fail may be tested using a Product Configuration that allows all Conformance Tests to pass.

JSONB1.2 A Product Configuration of an Operating Mode that causes the Product to report only version, usage, or diagnostic information is exempted from these compatibility rules.

JSONB1.3 An API Definition Product is exempt from all functional testing requirements defined here, except the signature tests.

JSONB2 Some Conformance Tests may have properties that may be changed. Properties that can be changed are identified in the configuration interview. Apart from changing such properties and other allowed modifications described in this User’s Guide (if any), no source or binary code for a Conformance Test may be altered in any way without prior written permission. Any such allowed alterations to the Conformance Tests will be provided via the Jakarta EE Specification Project website and apply to all vendor compatible implementations.

JSONB3 The testing tools supplied as part of the Test Suite or as updated by the Maintenance Lead must be used to certify compliance.

JSONB4 The Exclude List associated with the Test Suite cannot be modified.

JSONB5 The Maintenance Lead can define exceptions to these Rules. Such exceptions would be made available as above, and will apply to all vendor implementations.

JSONB6 All hardware and software component additions, deletions, and modifications to a Documented supporting hardware/software platform, that are not part of the Product but required for the Product to satisfy the compatibility requirements, must be Documented and available to users of the Product.

For example, if a patch to a particular version of a supporting operating system is required for the Product to pass the Conformance Tests, that patch must be Documented and available to users of the Product.

JSONB7 The Product must contain the full set of public and protected classes and interfaces for all the Libraries. Those classes and interfaces must contain exactly the set of public and protected methods, constructors, and fields defined by the Specifications for those Libraries. No subsetting, supersetting, or modifications of the public and protected API of the Libraries are allowed except only as specifically exempted by these Rules.

JSONB7.1 If a Product includes Technologies in addition to the Technology Under Test, then it must contain the full set of combined public and protected classes and interfaces. The API of the Product must contain the union of the included Technologies. No further modifications to the APIs of the included Technologies are allowed.

JSONB8 Except for tests specifically required by this TCK to be rebuilt (if any), the binary Conformance Tests supplied as part of the Test Suite or as updated by the Maintenance Lead must be used to certify compliance.

JSONB9 The functional programmatic behavior of any binary class or interface must be that defined by the Specifications.

4.3. Test Appeals Process

Jakarta has a well established process for managing challenges to its TCKs. Any implementor may submit a challenge to one or more tests in the JSON Binding TCK as it relates to their implementation. Implementor means the entity as a whole in charge of producing the final certified release. Challenges filed should represent the consensus of that entity.

4.3.1. Valid Challenges

Any test case (e.g., test class, @Test method), test case configuration (e.g., deployment descriptor), test beans, annotations, and other resources considered part of the TCK may be challenged.

The following scenarios are considered in scope for test challenges:

  • Claims that a test assertion conflicts with the specification.

  • Claims that a test asserts requirements over and above that of the specification.

  • Claims that an assertion of the specification is not sufficiently implementable.

  • Claims that a test is not portable or depends on a particular implementation.

4.3.2. Invalid Challenges

The following scenarios are considered out of scope for test challenges and will be immediately closed if filed:

  • Challenging an implementation’s claim of passing a test. Certification is an honor system and these issues must be raised directly with the implementation.

  • Challenging the usefulness of a specification requirement. The challenge process cannot be used to bypass the specification process and raise in question the need or relevance of a specification requirement.

  • Claims the TCK is inadequate or missing assertions required by the specification. See the Improvement section, which is outside the scope of test challenges.

  • Challenges that do not represent a consensus of the implementing community will be closed until such time that the community does agree or agreement cannot be made. The test challenge process is not the place for implementations to initiate their own internal discussions.

  • Challenges to tests that are already excluded for any reason.

  • Challenges that an excluded test should not have been excluded and should be re-added should be opened as a new enhancement request

Test challenges must be made in writing via the JSON Binding specification project issue tracker as described in TCK Test Appeals Steps.

All tests found to be invalid will be placed on the Exclude List for that version of the JSON Binding TCK.

4.3.3. TCK Test Appeals Steps

  1. Challenges should be filed via the Jakarta JSON Binding specification project’s issue tracker using the label challenge and include the following information:

    • The relevant specification version and section number(s)

    • The coordinates of the challenged test(s)

    • The exact TCK and exclude list versions

    • The implementation being tested, including name and company

    • The full test name

    • A full description of why the test is invalid and what the correct behavior is believed to be

    • Any supporting material; debug logs, test output, test logs, run scripts, etc.

  2. Specification project evaluates the challenge.
    Challenges can be resolved by a specification project lead, or a project challenge triage team, after a consensus of the specification project committers is reached or attempts to gain consensus fails. Specification projects may exercise lazy consensus, voting or any practice that follows the principles of Eclipse Foundation Development Process. The expected timeframe for a response is two weeks or less. If consensus cannot be reached by the specification project for a prolonged period of time, the default recommendation is to exclude the tests and address the dispute in a future revision of the specification.

  3. Accepted Challenges.
    A consensus that a test produces invalid results will result in the exclusion of that test from certification requirements, and an immediate update and release of an official distribution of the TCK including the new exclude list. The associated challenge issue must be closed with an accepted label to indicate it has been resolved.

  4. Rejected Challenges and Remedy.
    When a`challenge` issue is rejected, it must be closed with a label of invalid to indicate it has been rejected. There appeal process for challenges rejected on technical terms is outlined in Escalation Appeal. If, however, an implementer feels the TCK challenge process was not followed, an appeal issue should be filed with specification project’s TCK issue tracker using the label challenge-appeal. A project lead should escalate the issue with the Jakarta EE Specification Committee via email (jakarta.ee-spec@eclipse.org). The committee will evaluate the matter purely in terms of due process. If the appeal is accepted, the original TCK challenge issue will be reopened and a label of appealed-challenge added, along with a discussion of the appeal decision, and the challenge-appeal issue with be closed. If the appeal is rejected, the challenge-appeal issue should closed with a label of invalid.

  5. Escalation Appeal.
    If there is a concern that a TCK process issue has not been resolved satisfactorily, the Eclipse Development Process Grievance Handling procedure should be followed to escalate the resolution. Note that this is not a mechanism to attempt to handle implementation specific issues.

4.4. Successful Challenges

The following tests are exempt from TCK testing due to challenges:

Table 2. challenges
Class Method Reason

jakarta/jsonb/bind/tck/defaultmapping/dates/DatesMappingTest

testGregorianCalendarWithTimeMapping_from_standalone

https://github.com/jakartaee/platform-tck/issues/102

jakarta/jsonb/bind/tck/defaultmapping/collections/CollectionsMappingTest

testEnumMap_from_standalone

https://github.com/jakartaee/platform-tck/issues/103

jakarta/jsonb/bind/tck/defaultmapping/collections/CollectionsMappingTest

testEnumSet_from_standalone

https://github.com/jakartaee/platform-tck/issues/103

jakarta/jsonb/bind/tck/defaultmapping/basictypes/BasicJavaTypesMappingTest

testLongMapping_from_standalone

https://github.com/jakartaee/jsonb-api/issues/180

jakarta/jsonb/bind/tck/defaultmapping/bignumbers/BigNumbersMappingTest

testBigNumberMarshalling_from_standalone

https://github.com/jakartaee/jsonb-api/issues/180

4.5. Specifications for Jakarta JSON Binding

The Jakarta JSON Binding specification is available from the specification project web-site: https://jakarta.ee/specifications/jsonb/.

4.6. Libraries for Jakarta JSON Binding

The following is a list of the packages comprising the required class libraries for JSON Binding 3.1:

  • jakarta.json.bind

  • jakarta.json.bind.adapter

  • jakarta.json.bind.annotation

  • jakarta.json.bind.config

  • jakarta.json.bind.serializer

  • jakarta.json.bind.spi

For the latest list of packages, also see:

https://jakarta.ee/specifications/jsonb/

5. Installation

This chapter explains how to install the Jakarta JSON Binding TCK software.

After installing the software according to the instructions in this chapter, proceed to Setup and Configuration, for instructions on configuring your test environment.

Note

Although the JSON Binding 3.1 TCK is not depended on any particular build tool, it is convenient to install Apache Maven 3.6.3+ for setup and execution of tests. Any other build tools like Gradle and JUnit 4 Console Runner can also be used that is Jupiter API compatible.

5.1. Obtaining a Compatible Implementation

Each compatible implementation (CI) will provide instructions for obtaining their implementation. Eclipse Yasson 3.1 is a compatible implementation which may be obtained from https://projects.eclipse.org/projects/ee4j.yasson

5.2. Installing the Software

Before you can run the JSON Binding TCK tests, you must install and set up the following software components:

  • Java SE 17+

  • A CI for JSON Binding 3.1, one example is Eclipse Yasson 3.1

  • The JSON Binding 3.1 Vendor Implementation (VI)

  • Any Jupiter API compatible test runner (eg. Apache Maven 3.6.3+)

Follow these steps:

  1. Install the Java SE 17+ software, if it is not already installed.
    Download and install the Java SE 17+ software from http://www.oracle.com/technetwork/java/javase/downloads/index.html. Refer to the installation instructions that accompany the software for additional information.

  2. Install the build tool that will be used to run the TCK, if it is not already installed.
    It will be convenient to use Apache Maven 3.6.3+ for running the tests. The test kit is not depended on Maven, any build tool compatible with Jupiter API is suffitient.

  3. Install the JSON Binding TCK 3.1 software.

    1. Copy or download the JSON Binding TCK software to your local system.
      You can obtain the JSON Binding TCK software from the Jakarta EE site https://jakarta.ee/specifications/jsonb/.

    2. Use the unzip command to extract the bundle in the directory of your choice:
      unzip {TCKPackageName}

  4. Install a JSON Binding 3.1 Compatible Implementation.
    A Compatible Implementation is used to validate your initial configuration and setup of the JSON Binding TCK 3.1 tests, which are explained further in Setup and Configuration.
    The Compatible Implementations for JSON Binding are listed on the Jakarta EE Specifications web site: https://jakarta.ee/specifications/jsonb/.

  5. Install the JSON Binding VI to be tested.
    Follow the installation instructions for the particular VI under test.

6. Setup and Configuration

Note

The Jakarta EE Specification process provides for any number of compatible implementations. As additional implementations become available, refer to project or product documentation from those vendors for specific TCK setup and operational guidance.

This chapter describes how to set up the JSON Binding TCK. Before proceeding with the instructions in this chapter, be sure to install all required software, as described in Installation.

After completing the instructions in this chapter, proceed to Executing Tests, for instructions on running the JSON Binding TCK.

Note

The JSON Binding TCK is not depended on any particular build tool to run the tests. It will be convenient and advisable to create a Apache Maven project to setup and run the TCK. This chapter will henceforth use instructions and steps to provide setup with Apache Maven as a build tool.

6.1. Configuring Your Environment to Run the TCK Against the Reference Implementation

After configuring your environment as described in this section, continue with the instructions in Executing Tests.

Note

In these instructions, variables in angle brackets need to be expanded for each platform. For example, <JAVA_HOME> becomes $JAVA_HOME on Solaris/Linux and %JAVA_HOME% on Windows. In addition, the forward slashes (/) used in all of the examples need to be replaced with backslashes (\) for Windows. Finally, be sure to use the appropriate separator for your operating system when specifying multiple path entries (; on Windows, : on UNIX/Linux).

On Windows, you must escape any backslashes with an extra backslash in path separators used in any of the following properties, or use forward slashes as a path separator instead.

  1. Set the following environment variables in your shell environment:

    1. JAVA_HOME to the directory in which Java SE 17+ is installed

    2. M2_HOME to the directory in which the Apache Maven build tool is installed.

    3. {TechnologyHomeEnv} to the directory in which the JSON Binding 3.1 CI has been installed

    4. PATH to include the following directories: JAVA_HOME/bin, and M2_HOME/bin

  2. Set below Maven/System properties

    1. jimage.dir This property specifies the directory where Java 11+ modules will be expanded by the jimage tool for use in sigTestClasspath

    2. sigTestClasspath This property must be set when running signature tests. This property should be set to a list of jar files and/or directories which contain your Jakarta EE and Java SE classes. Paths must be separated by the appropriate path separator (';' windows, ':' Unixes).

    3. jsonb-impl.groupId property is set to the Maven Group Id of the CI to test.

    4. jsonb-impl.artifactId property is set to the Maven Artifact Id of the CI to test.

    5. jsonb-impl.version property is set to the Maven Version of the CI to test.

  3. Set the below jars to the classpath

    1. JAR file for the JSON Binding 3.1 CI.
      jakarta.json.bind-api.jar.

    2. JUnit 5 jars (5.7.2+)

    3. JSON Binding TCK tests (jakarta.json.bind:jakarta.json.bind-tck)

Example: Maven configuration
    <dependencies>
        <dependency>
          <groupId>CI.group.id</groupId>
          <artifactId>CI.artifact.id</artifactId>
          <version>CI.version</version>
          <scope>test</scope>
        </dependency>
        <dependency>
          <groupId>jakarta.json.bind</groupId>
          <artifactId>jakarta.json.bind-api</artifactId>
          <version>3.0.0</version>
          <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>jakarta.json</groupId>
            <artifactId>jakarta.json-api</artifactId>
            <version>2.1.0</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.weld.se</groupId>
            <artifactId>weld-se-core</artifactId>
            <version>5.0.0.Beta1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>jakarta.json.bind</groupId>
            <artifactId>jakarta.json.bind-tck</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

6.2. Configuring Your Environment to Run the TCK Against the Vendor Implementation

After configuring your environment as described in this section, continue with the instructions in Executing Tests.

Note

In these instructions, variables in angle brackets need to be expanded for each platform. For example, <JAVA_HOME> becomes $JAVA_HOME on Solaris/Linux and %JAVA_HOME% on Windows. In addition, the forward slashes (/) used in all of the examples need to be replaced with backslashes (\) for Windows. Finally, be sure to use the appropriate separator for your operating system when specifying multiple path entries (; on Windows, : on UNIX/Linux).

On Windows, you must escape any backslashes with an extra backslash in path separators used in any of the following properties, or use forward slashes as a path separator instead.

  1. Set the following environment variables in your shell environment:

    1. JAVA_HOME to the directory in which Java SE 17+ is installed

    2. M2_HOME to the directory in which the Apache Maven build tool is installed.

    3. {TechnologyHomeEnv} to the directory in which the JSON Binding 3.1 CI has been installed

    4. PATH to include the following directories: JAVA_HOME/bin, and M2_HOME/bin

  2. Set below Maven/System properties

    1. jimage.dir This property specifies the directory where Java 11+ modules will be expanded by the jimage tool for use in sigTestClasspath

    2. sigTestClasspath This property must be set when running signature tests. This property should be set to a list of jar files and/or directories which contain your Java EE and Java SE classes. Paths must be separated by the appropriate path separator (';' windows, ':' Unixes).

    3. jsonb-api.groupId property is set to the Maven Group Id of the VI to test.

    4. jsonb-api.artifactId property is set to the Maven Artifact Id of the VI to test.

    5. jsonb-api.version property is set to the Maven Version of the VI to test.

  3. Set the below jars to the classpath

    1. JAR file for the JSON Binding 3.1 VI.
      yasson.jar.

    2. JUnit 5 jars (5.7.2+)

    3. JSON Binding TCK tests (jakarta.json.bind:jakarta.json.bind-tck)

Example: Maven configuration
    <dependencies>
        <dependency>
          <groupId>VI.grou.id</groupId>
          <artifactId>VI.artefact.id</artifactId>
          <version>VI.version</version>
          <scope>test</scope>
        </dependency>
        <dependency>
          <groupId>org.eclipse</groupId>
          <artifactId>yasson</artifactId>
          <version>3.0.0-R1</version>
          <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>jakarta.json</groupId>
            <artifactId>jakarta.json-api</artifactId>
            <version>2.1.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.weld.se</groupId>
            <artifactId>weld-se-core</artifactId>
            <version>5.0.0.Beta1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>jakarta.json.bind</groupId>
            <artifactId>jakarta.json.bind-tck</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

6.3. Publishing the Test Applications

Not needed for the JSON Binding TCK.

7. Executing Tests

The JSON Binding TCK uses the Junit framework to execute the tests.

This chapter includes the following topics:

Note

The instructions in this chapter assume that you have installed and configured your test environment as described in Installation and Setup and Configuration respectively.

7.1. Starting the tests

The JSON Binding TCK can be run from the command line in your shell environment by executing tests from the TCK jar.

Note

The mvn command referenced in the following two procedures and elsewhere in this guide is the Apache Maven build tool, which will need to be downloaded separately.

7.1.1. To Run All Tests

To run all tests, enter the following command:

cd ${TechnologyHomeEnv}/bin
mvn verify

7.2. Running a Subset of the Tests

Use the following modes to run a subset of the tests:

7.2.1. To Run a Single Test

To run a single test, enter the following command:

cd ${TechnologyHomeEnv}/bin
mvn verify -Dtest=ee.jakarta.tck.json.bind.api.jsonb.JsonbTest

7.2.2. To Run a Subset of Tests

To run a subset of tests, enter the following command:

cd ${TechnologyHomeEnv}/bin
mvn verify -Dtest=ee.jakarta.tck.json.bind.api

7.2.3. To Run Signature Tests

To run the JSON Binding TCK Signature Tests, enter the following command:

cd ${TechnologyHomeEnv}/bin
mvn verify -Dtest=ee.jakarta.tck.json.bind.signaturetest.jsonb.JSONBSigTest

7.3. Running the TCK Against another CI

Some test scenarios are designed to ensure that the configuration and deployment of all the prebuilt JSON Binding TCK tests against one Compatible Implementation are successful operating with other compatible implementations, and that the TCK is ready for compatibility testing against the Vendor and Compatible Implementations.

  1. Verify that you have followed the configuration instructions in Configuring Your Environment to Run the TCK Against the Reference Implementation.

  2. Run the tests, as described in Starting the tests and, if desired, Running a Subset of the Tests.

7.4. Running the TCK Against a Vendor Implementation

This test scenario is one of the compatibility test phases that all Vendors must pass.

  1. Verify that you have followed the configuration instructions in Configuring Your Environment to Run the TCK Against the Vendor Implementation.

  2. Run the tests, as described in Starting the tests and, if desired, Running a Subset of the Tests.

7.5. Test Reports

A set of report files is created for every test run. These report files can be found in the target directory that the test is run. After a test run is completed, the Junit framework writes reports for the test run.

8. Debugging Test Problems

There are a number of reasons that tests can fail to execute properly. This chapter provides some approaches for dealing with these failures. Please note that most of these suggestions are only relevant when running the test harness in GUI mode.

This chapter includes the following topics:

8.1. Overview

The goal of a test run is for all tests in the test suite that are not filtered out to have passing results. If the root test suite folder contains tests with errors or failing results, you must troubleshoot and correct the cause to satisfactorily complete the test run.

  • Errors: Tests with errors could not be executed by the Junit framework. These errors usually occur because the test environment is not properly configured.

  • Failures: Tests that fail were executed but had failing results.

For every test run, the Junit framework creates a set of report files in the target directory.

If a large number of tests failed, you should read Configuration Failures to see if a configuration issue is the cause of the failures.

If a large number of tests failed, you should read Configuration Failures to see if a configuration issue is the cause of the failures.

8.2. Configuration Failures

Configuration failures are easily recognized because many tests fail the same way. When all your tests begin to fail, you may want to stop the run immediately and start viewing individual test output.

9. Assertion Details

This section lists the total number of assertions in the TCK, and provides details about each assertion. The assertions are categorized as JavaDoc Assertions and Specification Assertions.

9.1. JavaDoc Assertions

Table 3. Summary
Type Total Active Deprecated Removed

# of Assertions

108

100

1

7

# of Required Assertions

108

100

1

7

# of Optional Assertions

0

0

0

0
Detail
ID Return Method/Field Description Required Deprecated Testable

JSONB:JAVADOC:1

Object

jakarta.json.bind.Jsonb.fromJson(String, Class)

Reads in a JSON data from the specified string and return the resulting content tree.

true

true

JSONB:JAVADOC:2

Object

jakarta.json.bind.Jsonb.fromJson(String, Class) throws JsonbException

If any unexpected error(s) occur(s) during deserialization.

true

false

JSONB:JAVADOC:3

Object

jakarta.json.bind.Jsonb.fromJson(String, Type)

Reads in a JSON data from the specified string and return the resulting content tree.

true

true

JSONB:JAVADOC:4

Object

jakarta.json.bind.Jsonb.fromJson(String, Type) throws JsonbException

If any unexpected error(s) occur(s) during deserialization.

true

false

JSONB:JAVADOC:5

Object

jakarta.json.bind.Jsonb.fromJson(Reader, Class)

Reads in a JSON data from the specified Reader and return the resulting content tree.

true

true

JSONB:JAVADOC:6

Object

jakarta.json.bind.Jsonb.fromJson(Reader, Class) throws JsonbException

If any unexpected error(s) occur(s) during deserialization.

true

false

JSONB:JAVADOC:7

Object

jakarta.json.bind.Jsonb.fromJson(Reader, Type)

Reads in a JSON data from the specified Reader and return the resulting content tree.

true

true

JSONB:JAVADOC:8

Object

jakarta.json.bind.Jsonb.fromJson(Reader, Type) throws JsonbException

If any unexpected error(s) occur(s) during deserialization.

true

false

JSONB:JAVADOC:9

Object

jakarta.json.bind.Jsonb.fromJson(InputStream, Class)

Reads in a JSON data from the specified InputStream and return the resulting content tree.

true

true

JSONB:JAVADOC:10

Object

jakarta.json.bind.Jsonb.fromJson(InputStream, Class) throws JsonbException

If any unexpected error(s) occur(s) during deserialization.

true

false

JSONB:JAVADOC:11

Object

jakarta.json.bind.Jsonb.fromJson(InputStream, Type)

Reads in a JSON data from the specified InputStream and return the resulting content tree.

true

true

JSONB:JAVADOC:12

Object

jakarta.json.bind.Jsonb.fromJson(InputStream, Type) throws JsonbException

If any unexpected error(s) occur(s) during deserialization.

true

false

JSONB:JAVADOC:13

String

jakarta.json.bind.Jsonb.toJson(Object)

Writes the Java object tree with root object object to a String instance as JSON.

true

true

JSONB:JAVADOC:14

String

jakarta.json.bind.Jsonb.toJson(Object) throws JsonbException

If any unexpected problem occurs during the serialization, such as I/O error.

true

false

JSONB:JAVADOC:15

String

jakarta.json.bind.Jsonb.toJson(Object, Type)

Writes the Java object tree with root object object to a String instance as JSON.

true

true

JSONB:JAVADOC:16

String

jakarta.json.bind.Jsonb.toJson(Object, Type) throws JsonbException

If any unexpected problem occurs during the serialization, such as I/O error.

true

false

JSONB:JAVADOC:17

void

jakarta.json.bind.Jsonb.toJson(Object, Writer)

Writes the object content tree into a Writer character stream.

true

true

JSONB:JAVADOC:18

void

jakarta.json.bind.Jsonb.toJson(Object, Writer) throws JsonbException

If any unexpected problem occurs during the serialization.

true

false

JSONB:JAVADOC:19

void

jakarta.json.bind.Jsonb.toJson(Object, Type, Writer)

Writes the object content tree into a Writer character stream.

true

true

JSONB:JAVADOC:20

void

jakarta.json.bind.Jsonb.toJson(Object, Type, Writer) throws JsonbException

If any unexpected problem occurs during the serialization.

true

false

JSONB:JAVADOC:21

void

jakarta.json.bind.Jsonb.toJson(Object, OutputStream)

Writes the object content tree into output stream.

true

true

JSONB:JAVADOC:22

void

jakarta.json.bind.Jsonb.toJson(Object, OutputStream) throws JsonbException

If any unexpected problem occurs during the serialization.

true

false

JSONB:JAVADOC:23

void

jakarta.json.bind.Jsonb.toJson(Object, Type, OutputStream)

Writes the object content tree into output stream.

true

true

JSONB:JAVADOC:24

void

jakarta.json.bind.Jsonb.toJson(Object, Type, OutputStream) throws JsonbException

If any unexpected problem occurs during the serialization.

true

false

JSONB:JAVADOC:25

Jsonb

jakarta.json.bind.JsonbBuilder.build

Returns a new instance of jakarta.json.bind.Jsonb Jsonb based on the parameters and configuration specified previously in this builder.

true

true

JSONB:JAVADOC:26

Jsonb

jakarta.json.bind.JsonbBuilder.create

Create a new jakarta.json.bind.Jsonb instance using the default JsonbBuilder implementation provided as returned from jakarta.json.bind.spi.JsonbProvider#provider() method.

true

true

JSONB:JAVADOC:27

Jsonb

jakarta.json.bind.JsonbBuilder.create(JsonbConfig)

Create a new jakarta.json.bind.Jsonb instance using the default JsonbBuilder implementation provided as returned from jakarta.json.bind.spi.JsonbProvider#provider() method, configured with provided configuration.

true

true

JSONB:JAVADOC:28

JsonbBuilder

jakarta.json.bind.JsonbBuilder.newBuilder

Create a new JsonbBuilder instance as returned by the default jakarta.json.bind.spi.JsonbProvider#provider() method.

true

true

JSONB:JAVADOC:29

JsonbBuilder

jakarta.json.bind.JsonbBuilder.newBuilder(String)

Create a new JsonbBuilder instance as returned by jakarta.json.bind.spi.JsonbProvider#provider(String) method.

true

true

JSONB:JAVADOC:30

JsonbBuilder

jakarta.json.bind.JsonbBuilder.newBuilder(JsonbProvider)

Create a new JsonbBuilder instance as returned by provider#create call.

true

true

JSONB:JAVADOC:31

JsonbBuilder

jakarta.json.bind.JsonbBuilder.withConfig(JsonbConfig)

Set configuration which will be set to the newly created jakarta.json.bind.Jsonb Jsonb instance.

true

true

JSONB:JAVADOC:33

Map

jakarta.json.bind.JsonbConfig.getAsMap

Return all configuration properties as an unmodifiable map.

true

true

JSONB:JAVADOC:34

Optional

jakarta.json.bind.JsonbConfig.getProperty(String)

Return value of particular configuration property. The method can only be used to retrieve one of the standard JSON Binding properties defined in this class or a provider specific property. Attempting to get an undefined property will result in an empty Optional value. See Supported Properties.

true

true

JSONB:JAVADOC:35

JsonbConfig

jakarta.json.bind.JsonbConfig.JsonbConfig

true

true

JSONB:JAVADOC:36

JsonbConfig

jakarta.json.bind.JsonbConfig.setProperty(String, Object)

Set the particular configuration property to a new value. The method can only be used to set one of the standard JSON Binding properties defined in this class or a provider specific property.

true

true

JSONB:JAVADOC:51

JsonbException

jakarta.json.bind.JsonbException.JsonbException(String)

Constructs a new runtime exception with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to #initCause.

true

true

JSONB:JAVADOC:52

JsonbException

jakarta.json.bind.JsonbException.JsonbException(String, Throwable)

Constructs a new runtime exception with the specified detail message and cause. Note that the detail message associated with cause is not automatically incorporated in this runtime exception’s detail message.

true

true

JSONB:JAVADOC:53

Object

jakarta.json.bind.adapter.JsonbAdapter.adaptFromJson(Object)

This method is used on deserialization only. It contains a conversion logic from type Adapted to type Original.

true

true

JSONB:JAVADOC:54

Object

jakarta.json.bind.adapter.JsonbAdapter.adaptFromJson(Object) throws Exception

if there is an error during the conversion.

true

false

JSONB:JAVADOC:55

Object

jakarta.json.bind.adapter.JsonbAdapter.adaptToJson(Object)

This method is used on serialization only. It contains a conversion logic from type Original to type Adapted. After conversion Adapted type will be mapped to JSON the standard way.

true

true

JSONB:JAVADOC:56

Object

jakarta.json.bind.adapter.JsonbAdapter.adaptToJson(Object) throws Exception

if there is an error during the conversion.

true

false

JSONB:JAVADOC:57

String

jakarta.json.bind.annotation.JsonbDateFormat.locale

Custom java.util.Locale to use.

true

true

JSONB:JAVADOC:58

String

jakarta.json.bind.annotation.JsonbDateFormat.value

Specifies the date pattern to use.

true

true

JSONB:JAVADOC:60

String

jakarta.json.bind.annotation.JsonbNumberFormat.locale

Custom java.util.Locale to use.

true

true

JSONB:JAVADOC:61

String

jakarta.json.bind.annotation.JsonbNumberFormat.value

Specifies the number pattern to use.

true

true

JSONB:JAVADOC:63

String

jakarta.json.bind.annotation.JsonbProperty.value

Customized name of the field (or JavaBean property).

true

true

JSONB:JAVADOC:64

String[]

jakarta.json.bind.annotation.JsonbPropertyOrder.value

Order in which properties are serialized. Names must correspond to original names defined in Java class before any customization applied.

true

true

JSONB:JAVADOC:65

Class

jakarta.json.bind.annotation.JsonbTypeAdapter.value

Custom JsonbAdapter which provides custom mapping for given field or JavaBean property.

true

true

JSONB:JAVADOC:66

Class

jakarta.json.bind.annotation.JsonbTypeDeserializer.value

Custom JsonbDeserializer which provides custom mapping for given field or JavaBean property.

true

true

JSONB:JAVADOC:67

Class

jakarta.json.bind.annotation.JsonbTypeSerializer.value

Custom JsonbSerializer which provides custom mapping for given field or JavaBean property.

true

true

JSONB:JAVADOC:68

Class

jakarta.json.bind.annotation.JsonbVisibility.value

Custom property visibility strategy used to resolve visibility of the members.

true

true

JSONB:JAVADOC:69

String

jakarta.json.bind.config.PropertyNamingStrategy.translateName(String)

Translates the property name into its JSON field name representation.

true

true

JSONB:JAVADOC:70

boolean

jakarta.json.bind.config.PropertyVisibilityStrategy.isVisible(Field)

Responds whether the given field should be considered as the JsonbProperty.

true

true

JSONB:JAVADOC:71

boolean

jakarta.json.bind.config.PropertyVisibilityStrategy.isVisible(Method)

Responds whether the given method should be considered as the JsonbProperty.

true

true

JSONB:JAVADOC:78

JsonbBuilder

jakarta.json.bind.spi.JsonbProvider.create

Returns a new instance of jakarta.json.bind.JsonbBuilder JsonbBuilder class. jakarta.json.bind.JsonbBuilder JsonbBuilder provides necessary getter methods to access required parameters.

true

true

JSONB:JAVADOC:80

JsonbProvider

jakarta.json.bind.spi.JsonbProvider.provider

Creates a JSON Binding provider object by using the java.util.ServiceLoader#load(Class) method. The first provider of JsonbProvider class from list of providers returned by ServiceLoader.load call is returned. If there are no available service providers, this method tries to load the default service provider using Class#forName(String) method.

true

true

JSONB:JAVADOC:81

JsonbProvider

jakarta.json.bind.spi.JsonbProvider.provider(String)

Creates a JSON Binding provider object by using the java.util.ServiceLoader#load(Class) method, matching providerName. The first provider of JsonbProvider class from list of providers returned by ServiceLoader.load call, matching providerName is returned. If no such provider is found, JsonbException is thrown.

true

true

JSONB:JAVADOC:37__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withAdapters(JsonbAdapter[])

Property used to specify custom mapping adapters. Configures value of ADAPTERS property. Calling withAdapters more than once will merge the adapters with previous value.

true

true

JSONB:JAVADOC:37

JsonbConfig

jakarta.json.bind.JsonbConfig.withAdapters(JsonbAdapter[])

Property used to specify custom mapping adapters. Configures value of #ADAPTERS property. Calling withAdapters more than once will merge the adapters with previous value.

true

true

JSONB:JAVADOC:38__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withBinaryDataStrategy(String)

Property used to specify custom binary data strategy. Configures value of BINARY_DATA_STRATEGY property.

true

true

JSONB:JAVADOC:38

JsonbConfig

jakarta.json.bind.JsonbConfig.withBinaryDataStrategy(String)

Property used to specify custom binary data strategy. Configures value of #BINARY_DATA_STRATEGY property.

true

true

JSONB:JAVADOC:39__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withDateFormat(String, Locale)

Property used to specify custom date format. This format will be used by default for all date classes serialization and deserialization.

true

true

JSONB:JAVADOC:39

JsonbConfig

jakarta.json.bind.JsonbConfig.withDateFormat(String, Locale)

Property used to specify custom date format. This format will be used by default for all date classes serialization and deserialization. Configures values of #DATE_FORMAT and #LOCALE properties.

true

true

JSONB:JAVADOC:40__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withDeserializers(JsonbDeserializer[])

Property used to specify custom deserializers. Configures value of DESERIALIZERS property. Calling withDeserializers more than once will merge the deserializers with previous value.

true

true

JSONB:JAVADOC:40

JsonbConfig

jakarta.json.bind.JsonbConfig.withDeserializers(JsonbDeserializer[])

Property used to specify custom deserializers. Configures value of #DESERIALIZERS property. Calling withDeserializers more than once will merge the deserializers with previous value.

true

true

JSONB:JAVADOC:41__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withEncoding(String)

The binding operations will default to this property for encoding of JSON data. For input data (fromJson), selected encoding is used if the encoding cannot be detected automatically. Default value is 'UTF-8'. Configures value of ENCODING property.

true

true

JSONB:JAVADOC:41

JsonbConfig

jakarta.json.bind.JsonbConfig.withEncoding(String)

The binding operations will default to this property for encoding of JSON data. For input data (fromJson), selected encoding is used if the encoding cannot be detected automatically. Default value is 'UTF-8'. Configures value of #ENCODING property.

true

true

JSONB:JAVADOC:42__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withFormatting(Boolean)

Property used to specify whether or not the serialized JSON data is formatted with linefeeds and indentation. Configures value of FORMATTING property.

true

true

JSONB:JAVADOC:42

JsonbConfig

jakarta.json.bind.JsonbConfig.withFormatting(Boolean)

Property used to specify whether or not the serialized JSON data is formatted with linefeeds and indentation. Configures value of #FORMATTING property.

true

true

JSONB:JAVADOC:43__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withLocale(Locale)

Property used to specify custom locale.

true

true

JSONB:JAVADOC:43

JsonbConfig

jakarta.json.bind.JsonbConfig.withLocale(Locale)

Property used to specify custom locale. Configures value of #LOCALE property.

true

true

JSONB:JAVADOC:44__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withNullValues(Boolean)

Property used to specify whether null values should be serialized to JSON document or skipped. Configures value of NULL_VALUES property.

true

true

JSONB:JAVADOC:44

JsonbConfig

jakarta.json.bind.JsonbConfig.withNullValues(Boolean)

Property used to specify whether null values should be serialized to JSON document or skipped. Configures value of #NULL_VALUES property.

true

true

JSONB:JAVADOC:45__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyNamingStrategy(PropertyNamingStrategy)

Property used to specify custom naming strategy. Configures value of JSONB_PROPERTY_NAMING_STRATEGY property.

true

true

JSONB:JAVADOC:45

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyNamingStrategy(PropertyNamingStrategy)

Property used to specify custom naming strategy. Configures value of #PROPERTY_NAMING_STRATEGY property.

true

true

JSONB:JAVADOC:46__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyNamingStrategy(String)

Property used to specify custom naming strategy. Configures value of JSONB_PROPERTY_NAMING_STRATEGY property.

true

true

JSONB:JAVADOC:46

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyNamingStrategy(String)

Property used to specify custom naming strategy. Configures value of #PROPERTY_NAMING_STRATEGY property.

true

true

JSONB:JAVADOC:47__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyOrderStrategy(String)

Property used to specify property order strategy. Configures values of JSONB_PROPERTY_ORDER_STRATEGY property.

true

true

JSONB:JAVADOC:47

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyOrderStrategy(String)

Property used to specify property order strategy. Configures values of #PROPERTY_ORDER_STRATEGY property.

true

true

JSONB:JAVADOC:48__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyVisibilityStrategy(PropertyVisibilityStrategy)

Property used to specify custom property visibility strategy. Configures value of PROPERTY_VISIBILITY_STRATEGY property.

true

true

JSONB:JAVADOC:48

JsonbConfig

jakarta.json.bind.JsonbConfig.withPropertyVisibilityStrategy(PropertyVisibilityStrategy)

Property used to specify custom property visibility strategy. Configures value of #PROPERTY_VISIBILITY_STRATEGY property.

true

true

JSONB:JAVADOC:49__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withSerializers(JsonbSerializer[])

Property used to specify custom serializers. Configures value of SERIALIZERS property. Calling withSerializers more than once will merge the serializers with previous value.

true

true

JSONB:JAVADOC:49

JsonbConfig

jakarta.json.bind.JsonbConfig.withSerializers(JsonbSerializer[])

Property used to specify custom serializers. Configures value of #SERIALIZERS property. Calling withSerializers more than once will merge the serializers with previous value.

true

true

JSONB:JAVADOC:50__OLD

JsonbConfig

jakarta.json.bind.JsonbConfig.withStrictIJSON(Boolean)

Property used to specify whether strict I-JSON serialization compliance should be enforced. Configures value of STRICT_IJSON property.

true

true

JSONB:JAVADOC:50

JsonbConfig

jakarta.json.bind.JsonbConfig.withStrictIJSON(Boolean)

Property used to specify whether strict I-JSON serialization compliance should be enforced. Configures value of #STRICT_IJSON property.

true

true

JSONB:JAVADOC:59__OLD

boolean

jakarta.json.bind.annotation.JsonbNillable.value

True if field with null value should be serialized as key/value pair into JSON with null value.

true

true

JSONB:JAVADOC:59

boolean

jakarta.json.bind.annotation.JsonbNillable.value

Switches on/off serialization of properties with null value.

true

true

JSONB:JAVADOC:62__OLD

boolean

jakarta.json.bind.annotation.JsonbProperty.nillable

True if field with null value should be serialized as key/value pair into JSON with null value.

true

true

JSONB:JAVADOC:62

boolean

jakarta.json.bind.annotation.JsonbProperty.nillable

Switches on/off serialization of null values.

true

true

true

JSONB:JAVADOC:82

JsonbBuilder

jakarta.json.bind.JsonbBuilder.withProvider(JsonProvider)

Provides a JSON-P provider to be used for all JSON-P related operations.

true

true

JSONB:JAVADOC:83

JsonbConfig

jakarta.json.bind.JsonbConfig.withCreatorParametersRequired(boolean)

Property used to specify whether all creator parameters should be treated as required. Default value is false.

true

true

JSONB:JAVADOC:84

String

jakarta.json.bind.annotation.JsonbSubtype.alias

Type alias which is used instead of a class name.

true

true

JSONB:JAVADOC:85

Class

jakarta.json.bind.annotation.JsonbSubtype.type

An actual type bound to the alias.

true

true

JSONB:JAVADOC:86

String

jakarta.json.bind.annotation.JsonbTypeInfo.key

Key used for keeping the type information (alias). Default value is @type.

true

true

JSONB:JAVADOC:87

JsonbSubtype[]

jakarta.json.bind.annotation.JsonbTypeInfo.value

Allowed aliases of the handled type.

true

true

JSONB:JAVADOC:88

Object

jakarta.json.bind.serializer.DeserializationContext.deserialize(Class, JsonParser)

Deserialize JSON stream into instance of provided class using jakarta.json.stream.JsonParser. JsonParser cursor have to be at KEY_NAME before START_OBJECT / START_ARRAY, or at START_OBJECT / START_ARRAY to call this method. After deserialization is complete JsonParser will be at END_OBJECT / END_ARRAY for deserialized JSON structure. If method is called for the same type, which is deserializer bound to, deserializer recursion is suppressed. Otherwise deserializers are reentrant during deserialization process started by this method. JsonParser instance of JSONB runtime is shared with custom deserializer.

true

true

JSONB:JAVADOC:89

Object

jakarta.json.bind.serializer.DeserializationContext.deserialize(Type, JsonParser)

Deserialize JSON stream into instance of provided class using jakarta.json.stream.JsonParser. JsonParser cursor have to be at KEY_NAME before START_OBJECT / START_ARRAY, or at START_OBJECT / START_ARRAY to call this method. After deserialization is complete JsonParser will be at END_OBJECT / END_ARRAY for deserialized JSON structure. If method is called for the same type, which is deserializer bound to, deserializer recursion is suppressed. Otherwise deserializers are reentrant during deserialization process started by this method. JsonParser instance of JSONB runtime is shared with custom deserializer.

true

true

JSONB:JAVADOC:90

Object

jakarta.json.bind.serializer.JsonbDeserializer.deserialize(JsonParser, DeserializationContext, Type)

Deserialize JSON stream into object.

true

true

JSONB:JAVADOC:91

void

jakarta.json.bind.serializer.JsonbSerializer.serialize(Object, JsonGenerator, SerializationContext)

Serializes object into JSON stream.

true

true

JSONB:JAVADOC:92

void

jakarta.json.bind.serializer.SerializationContext.serialize(String, Object, JsonGenerator)

Serializes arbitrary object to JSON, using current jakarta.json.stream.JsonGenerator instance. Serialization is ran as serialization of a root type from user JsonbSerializer. JsonGenerator instance is shared with JSONB and user serializer.

true

true

JSONB:JAVADOC:93

void

jakarta.json.bind.serializer.SerializationContext.serialize(Object, JsonGenerator)

Serializes arbitrary object to JSON, using current jakarta.json.stream.JsonGenerator instance. Serialization is ran as serialization of a root type from user JsonbSerializer. JsonGenerator instance is shared with JSONB and user serializer. Method without key parameter is intended to serialize inside JSON_ARRAYs.

true

true

9.2. Specification Assertions

Table 4. Summary
Type Total Active Deprecated Removed

# of Assertions

171

170

0

1

# of Required Assertions

164

163

0

1

# of Optional Assertions

7

7

0

0
Detail
ID Chapter Section Description Required Dependency Implementation Specific Defined by Status Testable

JSONB:SPEC:JSB-3.1-1

3

3.1

JSON Binding implementations MUST support binding of JSON documents as defined in RFC 7159 JSON Grammar. Serialized JSON output MUST conform to the RFC 7159 JSON Grammar and be encoded in UTF-8 encoding as defined in Section 8.1 (Character Encoding) of RFC 7159

true

false

technology

active

false

JSONB:SPEC:JSB-3.1-2

3

3.1

Implementations MUST support deserialization of documents conforming to RFC 7159 JSON Grammar

true

false

technology

active

false

JSONB:SPEC:JSB-3.1-3

3

3.1

In addition, implementations SHOULD NOT allow deserialization of RFC 7159 non-conforming text (e.g. unsupported encoding, …​) and report error in such case

false

false

technology

active

false

JSONB:SPEC:JSB-3.1-4

3

3.1

Detection of UTF encoding of deserialized document is done as defined in the Section 3 (Encoding) of RFC 4627

true

false

technology

active

false

JSONB:SPEC:JSB-3.1-5

3

3.1

Implementations SHOULD ignore presence of UTF byte order mark (BOM) and not treat it as an error.

false

false

technology

active

true

JSONB:SPEC:JSB-3.2-1

3

3.2

Implementations SHOULD NOT allow unmarshalling of RFC 7159 non-conforming text (e.g. unsupported encoding) and report error in such case.

false

false

technology

active

false

JSONB:SPEC:JSB-3.2-2

3

3.2

Implementation SHOULD also report error also during unmarshalling operation, if it is not possible to represent JSON document value in the expected Java type

false

false

technology

active

false

JSONB:SPEC:JSB-3.3-1

3

3.3

Implementation MUST report binding of the following basic java classes and their corresponding primitive types

  • java.lang.String

  • java.lang.Character

  • java.lang.Byte

  • java.lang.Short

  • java.lang.Integer

  • java.lang.Long

  • java.lang.Float

  • java.lang.Double

  • java.lang.Boolean

true

false

technology

active

true

JSONB:SPEC:JSB-3.3.1-1

3

3.3.1

Instances of type java.lang.String and java.lang.Character are marshalled to JSON String values as defined within RFC 7159 Section 7 (Strings) in UTF-8 encoding without byte order mark.

true

false

technology

active

true

JSONB:SPEC:JSB-3.3.1-2

3

3.3.1

Implementations SHOULD support deserialization of JSON text in other (than UTF-8) UTF encodings into java.lang.String instances

false

false

technology

active

true

JSONB:SPEC:JSB-3.3.2-1

3

3.3.2

Serialization of type java.lang.Byte, Short, Integer, Long, Float, Double and their corresponding primitive types to JSON Number MUST follow the conversion process defined in javadoc specification for the corresponding toString method

true

false

technology

active

true

JSONB:SPEC:JSB-3.3.2-2

3

3.3.2

Deserialization of a JSON value into java.lang.Byte, Short, Integer, Long, Float, Double instance or corresponding primitive type MUST follow the conversion process as defined in the specification for their corresponding parse$Type method, such as java.lang.Byte.parseByte for Byte.

true

false

technology

active

true

JSONB:SPEC:JSB-3.3.3-1

3

3.3.3

Serialization of type java.lang.Boolean and its corresponding boolean primitive type to JSON value MUST follow conversion process defined in specification for java.lang.Boolean.toString method

true

false

technology

active

true

JSONB:SPEC:JSB-3.3.3-2

3

3.3.3

Deserialization of a JSON value into java.lang.Boolean instance or boolean primitive type MUST follow the conversion process as defined in specification for java.lang.Boolean.parseBoolean method.

true

false

technology

active

true

JSONB:SPEC:JSB-3.3.4-1

3

3.3.4

Serialization of type java.lang.Number (if their more concrete type is not defined elsewhere in this chapter) to JSON string MUST retrieve double value returned from java.lang.Number.doubleValue() method and converting the value to JSON Number as defined in subsection 3.3.2

true

false

technology

active

true

JSONB:SPEC:JSB-3.3.4-2

3

3.3.4

Deserialization of a JSON value into Java type java.lang.Number should return instance of java.math.BigDecimal by using conversion as defined in the specification for constructor of java.math.BigDecimal with java.lang.String.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4-1

3

3.4

Implementations MUST support binding of the following standard Java SE classes:

  • java.math.BigInteger

  • java.math.BigDecimal

  • java.net.URL

  • java.net.URI

  • java.util.Optional

  • java.util.OptionalInt

  • java.util.OptionalLong

  • java.util.OptionalDouble

  • java.util.UUID

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.1-1

3

3.4.1

Serialization of type java.math.BigInteger, BigDecimal to s JSON Number MUST follow the conversion process defined in specification for their toString method

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.1-2

3

3.4.1

Deserialization of JSON value into java.math.BigInteger, BigDecimal instance MUST follow the conversion process as defined in the specification for constructor of java.math.BigInteger, BigDecimal with java.lang.String.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.2-1

3

3.4.2

Serialization of type java.net.URL, URI to a JSON String value MUST follow the conversion process defined in specification for their toString method

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.2-2

3

3.4.2

Deserialization of a JSON value into java.net.URL, URI instance MUST follow the conversion process as defined in the specification for constructor of java.net.URL, URI with java.lang.String input.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.3-1

3

3.4.3

Non-empty instances of type java.util.Optional, OptionalInt, OptionalLong, OptionalDouble are serialized to a JSON value by retrieving their contained instance and converting it to JSON value based on its type and corresponding mapping definitions within this chapter.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.3-2

3

3.4.3

Class fields containing empty optional instances are treated as having a null value and serialized based on 3.14.1.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.3-3

3

3.4.3

Empty optional instances in array items are serialized as null.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.3-4

3

3.4.3

Deserializing into Optional, OptionalInt, OptionalLong, OptionalDouble return empty optional value for properties containing a null value.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.3-5

3

3.4.3

Otherwise any non-empty Optional, OptionalInt, OptionalLong, OptionalDouble value is constructed of type unmarshalled based on mappings defined in this chapter.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.3-6

3

3.4.3

Instances of type java.util.Optional T are serialized to a JSON value as JSON objects when T alone would be serialized as JSON object. When T would be serialized as a JSON value (e.g. java.lang.String, java.lang.Integer), an instance of java.util.Optional T is serialized as a JSON value (without curly brackets).

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.3-7

3

3.4.3

Deserialization of a JSON value into java.util.Optional(T) MUST be supported if deserialization of a JSON value into instance of T is supported.

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.4-1

3

3.4.4

Serialization of type java.util.UUID, UUID to a JSON String value MUST follow the conversion process defined in specification for their toString method

true

false

technology

active

true

JSONB:SPEC:JSB-3.4.4-2

3

3.4.4

Deserialization of a JSON value into java.util.UUID, UUID instance MUST follow the conversion process as defined in the specification for the static method java.util.UUID#fromString with java.lang.String input.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5-1

3

3.5

Implementations MUST support binding of the following standard Java date/time classes:

  • java.util.Date

  • java.util.Calendar

  • java.util.GregorianCalendar

  • java.util.TimeZone

  • java.util.SimpleTimeZone

  • java.time.Instant

  • java.time.Duration

  • java.time.Period

  • java.time.LocalDate

  • java.time.LocalTime

  • java.time.LocalDateTime

  • java.time.ZonedDateTime

  • java.time.ZoneId

  • java.time.ZoneOffset

  • java.time.OffsetDateTime

  • java.time.OffsetTime

true

false

technology

active

true

JSONB:SPEC:JSB-3.5-2

3

3.5

If not specified otherwise in this section, GMT standard time zone and offset specified from UTC Greenwich is used.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5-3

3

3.5

If not specified otherwise, date time format for marshalling and unmarshalling is ISO 8601 without offset, as specified in java.time.format.DateTimeFormatter.ISO_DATE.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5-4

3

3.5

Implementations MUST report error if the date/time string in JSON document does not correspond to the expected datetime format.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5-5

3

3.5

If in strict I-JSON compliance mode, default date format is changed as it’s described in 4.4.1.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.1-1

3

3.5.1

The serialization format of java.util.Date, Calendar, GregorianCalendar instances with no time information is ISO_DATE.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.1-2

3

3.5.1

If time information is present, the format is ISO_DATE_TIME

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.1-3

3

3.5.1

Implementations MUST support deserialization of both ISO_DATE and ISO_DATE_TIME into java.util.Date, Calendar and GregorianCalendar instances.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.2-1

3

3.5.2

Implementations MUST support deserialization of any time zone format specified in java.util.TimeZone into a field or property of type java.util.TimeZone and SimpleTimeZone.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.2-2

3

3.5.2

Implementations MUST report an error for deprecated three-letter time zone IDs as specified in java.util.Timezone.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.2-3

3

3.5.2

The serialization format of java.util.TimeZone and SimpleTimeZone is NormalizedCustomID as specified in java.util.TimeZone.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-1

3

3.5.3

The serialization output for a java.time.Instant instance MUST be in a ISO_INSTANT format, as specified in java.time.format.DateTimeFormatter.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-2

3

3.5.3

Implementations MUST support the deserialization of an ISO_INSTANT formatted JSON string to a java.time.Instant instance.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-3

3

3.5.3

Analogically, for other java.time.* classes, following mapping table matches Java types and corresponding formats:

  • java.time.Instant ISO_INSTANT

  • java.time.LocalDate ISO_LOCAL_DATE

  • java.time.LocalTime ISO_LOCAL_TIME

  • java.time.LocalDateTime ISO_LOCAL_DATE_TIME

  • java.time.ZonedDateTime ISO_ZONED_DATE_TIME

  • java.time.OffsetDateTime ISO_OFFSET_DATE_TIME

  • java.time.OffsetTime ISO_OFFSET_TIME

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-4

3

3.5.3

Implementations MUST support the deserialization of any time zone ID format specified in java.time.ZoneId into a field or property of type java.time.ZoneId.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-5

3

3.5.3

The serialization format of java.time.ZoneId is the normalized zone ID as specified in java.time.ZoneId.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-6

3

3.5.3

Implementations MUST support the deserialization of any time zone ID format specified in java.time.ZoneOffset into a field or property of type java.time.ZoneOffset.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-7

3

3.5.3

The serialization format of java.time.ZoneOffset is the normalized zone ID as specified in java.time.ZoneOffset.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-8

3

3.5.3

Implementations MUST support the deserialization of any duration format specified in java.time.Duration into a field or property of type java.time.Duration.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-9

3

3.5.3

This is super-set of ISO 8601 duration format. The serialization format of java.time.Duration is the ISO 8601 seconds based representation, such as PT8H6M12.345S.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-10

3

3.5.3

Implementations MUST support the deserialization of any period format specified in java.time.Period into a field or property of type java.time.Period.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-11

3

3.5.3

This is a super-set of ISO 8601 period format. The serialization format of java.time.Period is ISO 8601 period representation.

true

false

technology

active

true

JSONB:SPEC:JSB-3.5.3-12

3

3.5.3

A zero-length period is represented as zero days 'P0D'.

true

false

technology

active

true

JSONB:SPEC:JSB-3.6-1

3

3.6

For an unspecified output type of a deserialization operation, as well as where output type is specified as Object.class, implementations MUST deserialize a JSON document using Java runtime types specified in table below:

  • object java.util.Map<String,Object>

  • array java.util.List<Object>

  • string java.lang.String

  • number java.math.BigDecimal

  • true/false java.lang.Boolean

  • null null

true

false

technology

active

true

JSONB:SPEC:JSB-3.6-2

3

3.6

JSON object values are deserialized into an implementation of java.util.Map(String, Object) with a predictable iteration order.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7-1

3

3.7

Any instance passed to a deserialization operation must have a public or protected no-argument constructor. Implementations SHOULD throw an error if this condition is not met.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7-2

3

3.7

This limitation does not apply to serialization operations, as well as to classes which specify explicit instantiation methods as described in section 4.5.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.1-1

3

3.7.1

For a deserialization operation of a Java property, if a matching public setter method exists, the method is called to set the value of the property. If a matching setter method with private, protected, or defaulted to package-only access exists, then this field is ignored. If no matching setter method exists and the field is public, then direct field assignment is used.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.1-2

3

3.7.1

For a serialization operation, if a matching public getter method exists, the method is called to obtain the value of the property. If a matching getter method with private, protected, or defaulted to package-only access exists, then this field is ignored. If no matching getter method exists and the field is public, then the value is obtained directly from the field.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.1-3

3

3.7.1

JSON Binding implementations MUST NOT deserialize into transient, final or static fields and MUST ignore name/value pairs corresponding to such fields.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.1-4

3

3.7.1

Implementations MUST support serialization of final fields.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.1-5

3

3.7.1

Transient and static fields MUST be ignored during serialization operation.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.1-6

3

3.7.1

If a JSON document contains a name/value pair not corresponding to field or setter method, then this name/value pair MUST be ignored.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.1-7

3

3.7.1

Public getter/setter methods without a corresponding field MUST be supported. When only public getter/setter method without corresponding field is present in the class, the getter method is called to obtain the value to serialize, and the setter method is called during deserialization operation.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.2-1

3

3.7.2

Implementations MUST support the binding of public and protected nested classes.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.2-2

3

3.7.2

For deserialization operations, both nested and encapsulating classes MUST fulfill the same instantiation requirements as specified in 3.7.1.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.3-1

3

3.7.3

Implementations MUST support the binding of public and protected static nested classes.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.3-2

3

3.7.3

For deserialization operations, the nested class MUST fulfill the same instantiation requirements as specified in 3.7.1.

true

false

technology

active

true

JSONB:SPEC:JSB-3.7.4-1

3

3.7.4

Deserialization into anonymous classes is not supported. Serialization of anonymous classes is supported by default object mapping.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-1

3

3.8

Polymorphic type handling is supported for deserialization and serialization. Polymorphic handling is ensured by annotation JsonbTypeInfo and @JsonbSubtype.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-2

3

3.8

JsonbTypeInfo defines key name of the property to store type information in it and defines all the supported aliases using @JsonbSubtype annotations.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-3

3

3.8

@JsonbSubtype ensures proper and safe mapping between class alias and type.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-4

3

3.8

Implementation must validate mapped types if they are assignable from the annotated type. If not, an exception must be thrown.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-5

3

3.8

Type information is obtained from @JsonbSubtype annotation as a type alias mapped to the type. If no matching class is found for obtained alias during deserialization, an exception must be thrown.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-6

3

3.8

New property with type information is added to the serialized object.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-7

3

3.8

The property key name is taken from the key property of the annotation JsonbTypeInfo.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-8

3

3.8

This type information property key name has to be unique in the resulting JSON document. If any naming collision with class or any other JsonbTypeInfo properties occurs, an exception must be thrown.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-9

3

3.8

It is required for all polymorphism fields to be serialized as the first properties in the JSON and any actual object properties are serialized after.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-10

3

3.8

If no JsonbTypeInfo is used on handled class or its predecessors, it is not possible to ensure proper polymorphic type handling and in such cases deserialization is not supported.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-11

3

3.8

If there are multiple different type polymorphic customizations that need to be merged, an exception must be thrown.

true

false

technology

active

true

JSONB:SPEC:JSB-3.8-12

3

3.8

The order of the type information properties must be the same in which they appear in the polymorphic type chain.

true

false

technology

active

true

JSONB:SPEC:JSB-3.9-1

3

3.9

Serialization of an Enum instance to a JSON String value MUST follow the conversion process defined in javadoc specification for their name().

true

false

technology

active

true

JSONB:SPEC:JSB-3.9-2

3

3.9

Deserialization of a JSON value into an enum instance MUST be done by calling the enum’s valueOf(String) method.

true

false

technology

active

true

JSONB:SPEC:JSB-3.10-1

3

3.10

Implementations MUST support the deserialization of specific interfaces defined in 3.11 and 3.3.4.

true

false

technology

active

true

JSONB:SPEC:JSB-3.10-2

3

3.10

Deserialization to other interfaces is not supported and implementations SHOULD report error in such case.

false

false

technology

active

true

JSONB:SPEC:JSB-3.10-3

3

3.10

If a class property is defined with an interface and not concrete type, then the mapping for a serialized property is resolved based on its runtime type.

true

false

technology

active

true

JSONB:SPEC:JSB-3.11-1

3

3.11

Implementations MUST support binding of the following collection interfaces, classes and their implementations.

  • java.util.Collection

  • java.util.Map

  • java.util.Set

  • java.util.HashSet

  • java.util.NavigableSet

  • java.util.SortedSet

  • java.util.TreeSet

  • java.util.LinkedHashSet

  • java.util.TreeHashSet

  • java.util.HashMap

  • java.util.NavigableMap

  • java.util.SortedMap

  • java.util.TreeMap

  • java.util.LinkedHashMap

  • java.util.TreeHashMap

  • java.util.List

  • java.util.ArrayList

  • java.util.LinkedList

  • java.util.Deque

  • java.util.ArrayDeque

  • java.util.Queue

  • java.util.PriorityQueue

  • java.util.EnumSet

  • java.util.EnumMap

true

false

technology

active

true

JSONB:SPEC:JSB-3.11-2

3

3.11

Implementations of interfaces below must provide accessible default constructor. JSON Binding implementations MUST report unmarshalling error if default constructor is not present or is not in accessible scope.

true

false

technology

active

true

JSONB:SPEC:JSB-3.12-1

3

3.12

JSON Binding implementations MUST support binding of Java arrays of all supported Java types from this chapter into/from JSON array structures as defined in Section 5 of RFC 7159

true

false

technology

active

true

JSONB:SPEC:JSB-3.12-2

3

3.12

Arrays of primitive types and multi-dimensional arrays MUST be supported.

true

false

technology

active

true

JSONB:SPEC:JSB-3.13-1

3

3.13

Declared fields MUST be serialized in lexicographical order into the resulting JSON document. In case of inheritance, declared fields of super class MUST be serialized before declared fields of child class.

true

false

technology

active

true

JSONB:SPEC:JSB-3.13-2

3

3.13

When deserializing a JSON document, declared fields MUST be set in the order of attributes present in the JSON document.

true

false

technology

active

true

JSONB:SPEC:JSB-3.14.1-1

3

3.14.1

The result of serializing a java field with a null value is the absence of the property in the resulting JSON document.

true

false

technology

active

true

JSONB:SPEC:JSB-3.14.1-2

3

3.14.1

The deserialization operation of a property absent in JSON document MUST not set the value of the field, the setter (if available) MUST not be called, and thus original value of the field MUST be preserved.

true

false

technology

active

true

JSONB:SPEC:JSB-3.14.1-3

3

3.14.1

The deserialization operation of a property with a null value in a JSON document MUST set the value of the field to null value (or call setter with null value if setter is present). The exception is java.util.Optional, OptionalInt, OptionalLong, OptionalDouble instances. In this case the value of the field is set to an empty optional value.

true

false

technology

active

true

JSONB:SPEC:JSB-3.14.2-1

3

3.14.2

The result of deserialization n-ary array represented in JSON document is n-ary Java array.

true

false

technology

active

true

JSONB:SPEC:JSB-3.14.2-2

3

3.14.2

Null value in JSON array is represented by null value in Java array.

true

false

technology

active

true

JSONB:SPEC:JSB-3.14.2-3

3

3.14.2

Serialization operation on Java array with null value at index i MUST output null value at index i of the array in resulting JSON document.

true

false

technology

active

true

JSONB:SPEC:JSB-3.15-1

3

3.15

According to RFC 7159 Section 7 , every Java identifier name can be transformed using identity function into a valid JSON String. Identity function MUST be used for transforming Java identifier names into name Strings in JSON document.

true

false

technology

active

true

JSONB:SPEC:JSB-3.15-2

3

3.15

For deserialization operations defined in 3.6 section, identity function is used to transform JSON name strings into Java String instances in the resulting map Map(String, Object).

true

false

technology

active

true

JSONB:SPEC:JSB-3.15-3

3

3.15

Identity function is used also for other deseralization operations.

true

false

technology

removed

true

JSONB:SPEC:JSB-3.15-4

3

3.15

If a Java identifier with corresponding name does not exist or is not accessible, the implementations MUST report error.

true

false

technology

active

true

JSONB:SPEC:JSB-3.16-1

3

3.16

JSON Binding implementation MUST serialize numbers that express greater magnitude or precision than an IEEE 754 double precision number as strings.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17-1

3

3.17

JSON Binding implementations MUST support binding of generic types.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17-2

3

3.17

Due to type erasure, there are situations when it is not possible to obtain generic type information. There are two ways for JSON Binding implementations to obtain generic type information. If there is a class file available (in the following text referred as static type information), it is possible to obtain generic type information (effectively generic type declaration) from Signature attribute (if this information is present).

true

false

technology

active

true

JSONB:SPEC:JSB-3.17-3

3

3.17

The second option is to provide generic type information at runtime. To provide generic type information at runtime, an argument of java.lang.reflect.Type MUST be passed to Jsonb::toJson or to Jsonb::fromJson method.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-1

3

3.17.1

There are several levels of information JSON Binding implementations may obtain about the type of field/class/interface:

  1. runtime type provided via java.lang.reflect.Type parameter passed to Jsonb::toJson or Jsonb::fromJson method

  2. static type provided in class file (effectively stored in Signature attribute)

  3. raw type

  4. no information about the type

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-2

3

3.17.1

If there is no information about the type, JSON Binding implementation MUST treat this type as java.lang.Object.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-3

3

3.17.1

If only raw type of given field/class/interface is known, then the type MUST be treated like raw type.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-4

3

3.17.1

For example, if the only available information is that given field/class/interface is of type java.util.ArrayList, than the type MUST be treated as java.util.ArrayList Object. JSON Binding implementations MUST use the most specific type derived from the information available.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-5

3

3.17.1

Let’s consider situation where there is only static type information of a given field/class/interface known, and there is no runtime type information available. Let GenericClass T1. . .Tn be part of generic type declaration, where GenericClass is name of the generic type and T1. . .Tn are type parameters. For every Ti, where i in 1. . .n, there are 3 possible options:

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-6

3

3.17.1

  1. Ti is concrete parameter type

    • the most specific parameter type MUST be given concrete parameter type Ti.

  2. Ti is bounded parameter type

  3. Ti is wildcard parameter type without bounds

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-7

3

3.17.1

For bounded parameter type, using bounds B1. . .Bm. If m = 1, then the most specific parameter type MUST be derived from the given bound B1.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-8

3

3.17.1

If B1 is class or interface, the most specific parameter type MUST be the class or interface.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-9

3

3.17.1

Otherwise, the most specific parameter type SHOULD be java.lang.Object.

false

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-10

3

3.17.1

If multiple bounds are specified, the first step is to resolve every bound separately. Let’s define result of such resolution as S1. . . Sm specific parameter types. If S1. . . Sm are java.lang.Object, then the bounded parameter type Ti MUST be java.lang.Object.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-11

3

3.17.1

If there is exactly one Sk, where 1 ⇐ k ⇐ m is different than java.lang.Object, then the most specific parameter type for this bounded parameter type Ti MUST be Sk.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-12

3

3.17.1

If there exists Sk1; Sk2, where 1 ⇐ k1 ⇐ k2 ⇐ m, then the most specific parameter type is Sk1.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-13

3

3.17.1

For wildcard parameter type without bounds, the most specific parameter type MUST be java.lang.Object.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-14

3

3.17.1

Any unresolved type parameter MUST be treated as java.lang.Object.

true

false

technology

active

true

JSONB:SPEC:JSB-3.17.1-15

3

3.17.1

If runtime type is provided via java.lang.reflect.Type parameter passed to Jsonb::toJson or Jsonb::fromJson method, than that runtime type overrides static type declaration wherever applicable

true

false

technology

active

true

JSONB:SPEC:JSB-3.18-1

3

3.18

When JSON Binding implementation encounters key in key/value pair that it does not recognize, it should treat the rest of the JSON document as if the element simply did not appear, and in particular, the implementation MUST NOT treat this as an error condition.

true

false

technology

active

true

JSONB:SPEC:JSB-3.19-1

3

3.19

JSON Binding implementations MUST NOT produce JSON documents with members with duplicate names. In this context, "duplicate" means that the names, after processing any escaped characters, are identical sequences of Unicode characters.

true

false

technology

active

true

JSONB:SPEC:JSB-3.19-2

3

3.19

When non-unique property (after override and rename) is found, implementation MUST throw an exception. This doesn’t apply for customized user serialization behavior implemented with the usage of JsonbAdapter mechanism.

true

false

technology

active

true

JSONB:SPEC:JSB-3.20-1

3

3.20

JSON Binding implementations MUST support binding of the following JSON Processing types.

  • jakarta.json.JsonObject

  • jakarta.json.JsonArray

  • jakarta.json.JsonStructure

  • jakarta.json.JsonValue

  • jakarta.json.JsonPointer

  • jakarta.json.JsonString

  • jakarta.json.JsonNumber

true

false

technology

active

true

JSONB:SPEC:JSB-3.20-2

3

3.20

Serialization of supported jakarta.json.* objects/interfaces/fields MUST have the same result as serialization these objects with jakarta.json.JsonWriter.

true

false

technology

active

true

JSONB:SPEC:JSB-3.20-3

3

3.20

Deserialization into supported jakarta.json.* objects/interfaces/fields MUST have the same result as deserialization into such objects with jakarta.json.JsonReader.

true

false

technology

active

true

JSONB:SPEC:JSB-3.20-4

3

3.20

If the null value is deserialized into the JsonValue, it is handled as JsonValue.NULL. JsonValue.NULL is not assigned as a default value if no value is set.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.1-1

4

4.1.1

JSON Binding implementations MUST NOT serialize fields, JavaBean properties or types annotated with jakarta.json.bind.annotation.JsonbTransient.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.1-2

4

4.1.1

JsonbTransient annotation is mutually exclusive with all other JSON Binding defined annotations. Implementations must throw JsonbException in the following cases: Class field is annotated with @JsonbTransient. Exception must be thrown when this field, getter or setter is annotated with other JSON Binding annotations.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.1-3

4

4.1.1

Getter is annotated with @JsonbTransient. Exception is thrown if when the field or this getter are annotated with other JSON Binding annotations. Exception is not thrown if JSON Binding annotations are presented on the setter.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.1-4

4

4.1.1

Setter is annotated with @JsonbTransient. Exception is thrown if when the field or this setter are annotated with other JSON Binding annotations. Exception is not thrown if JSON Binding annotations are presented on the getter.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.2-1

4

4.1.2

To provide custom name for given field (or JavaBean property), jakarta.json.bind.annotation.JsonbProperty may be used. JsonbProperty annotation may be specified on field, getter or setter method. If specified on field, custom name is used both for serialization and deserialization.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.2-2

4

4.1.2

If jakarta.json.bind.annotation.JsonbProperty is specified on getter method, it is used only for serialization.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.2-3

4

4.1.2

If jakarta.json.bind.annotation.JsonbProperty is specified on setter method, it is used only for deserialization.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.2-4

4

4.1.2

It is possible to specify different values for getter and setter method for jakarta.json.bind.annotation.JsonbProperty annotation. In such case the different custom name will be used for serialization and deserialization.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.3-1

4

4.1.3

The way to set custom property naming strategy is to use jakarta.json.bin.JsonbConfig::withPropertyNamingStrategy method.

true

false

technology

active

true

JSONB:SPEC:JSB-4.1.4-1

4

4.1.4

If duplicate name is found exception MUST be thrown. The definition of duplicate (non-unique) property can be found in 3.19.

true

false

technology

active

true

JSONB:SPEC:JSB-4.2

4

4.2

The way to set custom property order strategy is to use jakarta.json.bin.JsonbConfig::withPropertyOrderStrategy method.

true

false

technology

active

true

JSONB:SPEC:JSB-4.2-2

4

4.2

To customize the order of serialized properties only for one specific type, JSON Binding provides jakarta.json.bind.annotation.JsonbPropertyOrder annotation. Order specified by JsonbPropertyOrder annotation overrides order specified by PropertyOrderStrategy.

true

false

technology

active

true

JSONB:SPEC:JSB-4.3-1

4

4.3

If annotations (JsonbNillable or JsonbProperty) on different level apply to the same field (or JavaBean property) or if there is config wide configuration and some annotation (JsonbNillable or JsonbProperty) which apply to the same field (or JavaBean property), the annotation with the smallest scope applies.

true

false

technology

active

true

JSONB:SPEC:JSB-4.3-2

4

4.3

JsonbNillable and JsonbProperty are applied on the same level, JsonbNillable takes precedence.

true

false

technology

active

true

JSONB:SPEC:JSB-4.3.1-1

4

4.3.1

When given object (type or package) is annotated with jakarta.json.bind.annotation.JsonbNillable annotation, the result of null value will be presence of associated property in JSON document with explicit null value.

true

false

technology

active

true

JSONB:SPEC:JSB-4.3.1-2

4

4.3.1

The same behavior as JsonbNillable, but only at field, parameter and method (JavaBean property) level is provided by jakarta.json.bind.annotation.JsonbProperty annotation with its nillable parameter. This option is currently deprecated, and it is recommended to use jakarta.json.bind.annotation.JsonbNillable instead.

true

false

technology

active

true

JSONB:SPEC:JSB-4.3.1-3

4

4.3.1

JSON Binding implementations MUST implement override of annotations according to target of the annotation (FIELD, PARAMETER, METHOD, TYPE, PACKAGE). Type level annotation overrides behavior set at the package level. Method, parameter or field level annotation overrides behavior set at the type level.

true

false

technology

active

true

JSONB:SPEC:JSB-4.3.2-1

4

4.3.2

The way to enforce serialization of null values, is to call method jakarta.json.bind.JsonbConfig::withNullValues with parameter true. The way to skip serialization of null values is to call method jakarta.json.bind.JsonbConfig::withNullValues with parameter false.

true

false

technology

active

true

JSONB:SPEC:JSB-4.4-1

4

4.4

To enforce strict compliance of serialized JSON documents, JSON Binding implementations MUST implement configuration option jsonb.i-json.strict-ser-compliance.

true

false

technology

active

true

JSONB:SPEC:JSB-4.4.1-1

4

4.4.1

Uppercase rather than lowercase letters MUST be used.

true

false

technology

active

true

JSONB:SPEC:JSB-4.4.1-2

4

4.4.1

The timezone MUST always be included and optional trailing seconds MUST be included even when their value is 00.

true

false

technology

active

true

JSONB:SPEC:JSB-4.4.1-3

4

4.4.1

JSON Binding implementations MUST serialize java.util.Date, java.util.Calendar, java.util.GregorianCalendar, java.time.LocalDate, java.time.LocalDateTime and java.time.Instant in the same format as java.time.ZonedDateTime.

true

false

technology

active

true

JSONB:SPEC:JSB-4.4.1-4

4

4.4.1

The result of serialization of duration must conform to the duration production in Appendix A of RFC 3339, with the same additional restrictions

true

false

technology

active

true

JSONB:SPEC:JSB-4.5-1

4

4.5

At most one JsonbCreator annotation can be used to annotate custom constructor or static void factory method in a class, otherwise JsonbException MUST be thrown.

true

false

technology

active

true

JSONB:SPEC:JSB-4.5-2

4

4.5

Factory method annotated with JsonbCreator annotation should return instance of particular class this annotation is used for, otherwise JsonbException MUST be thrown.

true

false

technology

active

true

JSONB:SPEC:JSB-4.5-3

4

4.5

Mapping between parameters of constructor/factory method annotated with JsonbCreator and JSON fields is defined using JsonbProperty annotation on all parameters. If the JsonbProperty annotation on parameters is not used, then parameters should be mapped from JSON fields with the same name. In this case the proper mapping is NOT guaranteed. All the JsonbCreator parameters are treated as optional by default. See Optional parameter values chapter for default optional parameter values. All the JsonbCreator parameters can be turned to required by using configuration method Config::withCreatorParametersRequired. If a required field for a parameter mapping does not exist in the JSON document, then JsonbException MUST be thrown.

true

false

technology

active

true

JSONB:SPEC:JSB-4.5.1-1

4

4.5

When a property is marked as optional, the proper default should be used. If the parameter is any type other than Optional or its variations, then the null value is used. If the parameter is java.util.Optional, OptionalInt, OptionalLong, OptionalDouble, then the corresponding empty object must be used. Primitive types cannot accept null values, so a corresponding value is required as listed in the following table:.

true

false

technology

active

true

JSONB:SPEC:JSB-4.6-1

4

4.5

To customize scope and field access strategy as specified in section 3.7.1, it is possible to specify jakarta.json.bind.annotation.JsonbVisibility annotation or to override default behavior globally calling JsonbConfig::withPropertyVisibilityStrategy method with given custom property visibility strategy.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.1-1

4

4.7.1

On serialization of Original type JSONB calls JsonbAdapter::adaptToJson method of the adapter to convert Original to Adapted and serializes Adapted the standard way. On deserialization JSONB deserializes Adapted from JSON and converts it to Original using JsonbAdapter::adaptFromJson method.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.1-2

4

4.7.1

There are two ways how to register JsonbAdapter: Using JsonbConfig::withAdapters method & Annotating a class field with JsonbTypeAdapter annotation.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.1-3

4

4.7.1

Implementations must provide a CDI support in adapters to allow injection of CDI managed beans into it.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.1-4

4

4.7.1

JsonbAdapter registered via JsonbConfig::withAdapters is visible to all serialize/deserialize operations performed with given JsonbConfig. JsonbAdapter registered with annotation is visible to serialize/deserialize operation used only for annotated field.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.1-5

4

4.7.1

It is possible to annotate JsonbCreator parameter with JsonbTypeAdapter and provide adapter for a parameter this way. However, if JsonbTypeAdapter annotation is provided to any other parameter (such as setter method parameter) it will be ignored.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.2-1

4

4.7.2

Serializer is a class implementing jakarta.json.bind.serializers.JsonbSerializer interface. It is used to serialize the type it’s registered on (Original). On marshalling of Original type JSONB calls JsonbSerializer::serialize method. This method has to contain a custom code to serialize Original type using provided JsonpGenerator.Deserializer is a class implementing jakarta.json.bind.serializers.JsonbDeserializer interface. It is used to deserialize the type it’s registered on (Original). On deserialization of Original type JSONB calls JsonbDeserializer::deserialize method. This method has to contain a custom code to deserialize Original type using provided JsonpParser. There are two ways how to register JsonbSerializer/JsonbDeserializer:Using JsonbConfig::withSerializers/ JsonbConfig::withDeserializers method;

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.2-2

4

4.7.2

Annotating a type with JsonbSerializer/JsonbDeserializer annotation.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.2-3

4

4.7.2

Implementations must provide a CDI support in serializers/deserializers to allow injection of CDI managed beans into it.

true

false

technology

active

true

JSONB:SPEC:JSB-4.7.2-4

4

4.7.2

It is possible to annotate JsonbCreator parameter with JsonbTypeDeserializer and provide deserializer for a parameter this way. However, if JsonbTypeDeserializer annotation is provided to any other parameter (such as setter method parameter) it will be ignored.

true

false

technology

active

true

JSONB:SPEC:JSB-4.8-1

4

4.8

JsonbDateFormat annotation can be applied to the following targets: field, method, type, parameter, package

true

false

technology

active

true

JSONB:SPEC:JSB-4.8-2

4

4.8

Annotation applied to more specific target overrides the same annotation applied to target with wider scope and global configuration. For example, annotation applied to type target will override the same annotation applied to package target.

true

false

technology

active

true

JSONB:SPEC:JSB-4.8-3

4

4.8

Default date format and default locale can be customized globally using jakarta.json.bind.JsonbConfig::withDateFormat and jakarta.json.bind.JsonbConfig::withLocale methods.

true

false

technology

active

true

JSONB:SPEC:JSB-4.9-1

4

4.9

JsonbNumberFormat annotation can be applied to the following targets: field, getter/setter, method, type, parameter, package

true

false

technology

active

true

JSONB:SPEC:JSB-4.9-2

4

4.9

Annotation applied to more specific target overrides the same annotation applied to target with wider scope. For example, annotation applied to type target will override the same annotation applied to package target.

true

false

technology

active

true

JSONB:SPEC:JSB-4.10-1

4

4.10

The way to set custom binary data handling strategy is to use jakarta.json.bin.JsonbConfig::withBinaryDataStrategy method.

true

false

technology

active

true

Appendix A: Frequently Asked Questions

This appendix contains the following questions.

A.1. Where do I start to debug a test failure?

See Debugging Test Problems, for more information.

A.2. How do I restart a crashed test run?

If you need to restart a test run, you can figure out which test crashed the test suite by looking at the logs.

A.3. What would cause tests be added to the exclude list?

The exclude file ({excludeListFileName}) contains all tests that are not required to be run. The following is a list of reasons for a test to be included in the Exclude List:

  • An error in a Compatible Implementation that does not allow the test to execute properly has been discovered.

  • An error in the specification that was used as the basis of the test has been discovered.

  • An error in the test has been discovered.

Appendix B: Rebuild Rules

Rebuild Rules is not used for the JSON Binding TCK.