1. Developer's Guide
  2. Features of Oracle Data Provider for .NET
  3. Native JSON Support

Native JSON Support

Oracle Database 20c adds a native JavaScript Object Notation (JSON) data type. ODP.NET Core, managed, and unmanaged drivers support this native JSON data type starting with version 21.

In ODP.NET, the database JSON data type can be retrieved or passed to the database. When using a .NET string or OracleString, it can be bound as a parameter using the OracleDbType.Json enumeration value. This enumeration value directs ODP.NET to perform decoding from and encoding to the native Oracle Database JSON binary format, OSON, on the client side, offloading the task from the server side.

Alternatively, JSON data can be bound as parameters to other ODP.NET and .NET data types or not use the OracleDbType.Json enumeration value. Oracle Database will then implicitly encode to and decode from OSON to the desired data type format instead of the client in these cases. In DataSet, the Oracle JSON type is converted to and stored as either a .NET string or OracleString.

Managed ODP.NET and ODP.NET Core JSON features require the System.Text.Json assembly be included as a project dependency. ODP.NET does not add the System.Text.Json package as a dependency itself. In many cases, .NET Core 3.1 and higher does automatically include this assembly with the .NET runtime, while .NET Framework 4.8 does not.

Unmanaged ODP.NET does not have a requirement for System.Text.Json.

JSON Numeric Values

For managed ODP.NET and ODP.NET Core, JSON documents bound as OracleDbType.Json input parameters have a 28 precision upper limit for numeric values. In all other cases, up to 38 precision will be retained for JSON numeric values when sent to or retrieved from the database.

Unmanaged ODP.NET supports JSON numeric values with a maximum precision of 38, as does the database.

If a JSON document bound as OracleDbType.Json contains numeric values with higher precision than can be retained, then ODP.NET will round the value to the maximum supported precision. If more precision must be retained than the maximum, then store the numeric value as a string by placing double quotes around the JSON value before binding the JSON document as an input parameter.