DBMS_JSON_SCHEMA

106 DBMS_JSON_SCHEMA

The DBMS_JSON_SCHEMA package provides subprograms for validating and generating JavaScript Object Notation (JSON) schemas that are stored in Oracle Database.

This chapter contains the following topics:

106.1 DBMS_JSON_SCHEMA Security Model

The DBMS_JSON_SCHEMA package is owned by the SYS account.

The PUBLIC account is granted the EXECUTE privilege on the DBMS_JSON_SCHEMA package.

The DBMS_JSON_SCHEMA package is defined with the AUTHID CURRENT_USER clause.

The user who invokes the DBMS_JSON_SCHEMA.DESCRIBE() function must have sufficient privileges on the object that is being described.

106.2 DBMS_JSON_SCHEMA Constants

The DBMS_JSON_SCHEMA package uses the following constants for schema validation.

Table 106-1 DBMS_JSON_SCHEMA Constants for Schema Validation

Name	Value	Description
RAISE_ERROR	1	Raise errors for invalid schemas.
RAISE_NONE	0	Do not raise errors for invalid schemas.
SCHEMA_INVALID	0	The schema is not valid.
SCHEMA_VALID	1	The schema is valid.

See Also:

JSON Developer's Guide

106.3 Summary of DBMS_JSON_SCHEMA Subprograms

This table lists the DBMS_JSON_SCHEMA subprograms and briefly describes them.

DBMS_JSON_SCHEMA Package Subprograms

Subprogram	Description
DESCRIBE Function	Creates a schema from a specified object (table, view, object type; or a synonym resolving to a table, view, duality view, object or collection type, or domain).
IS_SCHEMA_VALID Function	Check the validity of a JSON schema.
IS_VALID Function	Check the validity of JSON data for a specified schema (function).
IS_VALID Procedure	Check the validity of JSON data for a specified schema (procedure).
VALIDATE_REPORT Function	Reads the error report from the result of a schema validation.

106.3.1 DESCRIBE Function

This procedure creates a schema from a specified object.

See Also:

Oracle Database JSON Developer’s Guide

Syntax

FUNCTION DESCRIBE(
   object_name IN VARCHAR2,
   owner_name  IN VARCHAR2  DEFAULT NULL,
   column_name IN VARCHAR2  DEFAULT NULL)
RETURN JSON;

Parameters

Table 106-2 DESCRIBE Function Parameters

Parameter	Description
`object_name`	The object to use to create the schema. The object can be a table, view, object type, or a synonym resolving to a table, view, duality view, object type, collection type, or domain.
`owner_name`	The name of the user who the schema is created for. If the `owner_name` value is NULL, the table is created in the current user’s schema.
`column_name`	If a column name is specified, the schema returned is only for the column in the table or view. The `column_name` argument can be used only with table or view objects.

106.3.2 IS_SCHEMA_VALID Function

This function checks a schema for validity.

See Also:

Oracle Database JSON Developer’s Guide

Syntax

FUNCTION IS_SCHEMA_VALID(
   json_data   IN   JSON)
RETURN PLS_INTEGER;

Parameters

Table 106-3 DESCRIBE Function Parameters

Parameter	Description
`json_data`	The schema to check for validity.

The function returns 0 if the schema is not valid.

106.3.3 IS_VALID Function

This function checks the validity of JSON data for a specified schema.

See Also:

Oracle Database JSON Developer’s Guide

Syntax

FUNCTION IS_VALID(
   json_data   IN   JSON,
   json_schema IN   JSON,
   raise_err   IN   PLS_INTEGER
   DEFAULT DBMS_JSON_SCHEMA.RAISE_NONE)
RETURN PLS_INTEGER;

Parameters

Table 106-4 IS_VALID Function Parameters

Parameter	Description
`json_data`	The JSON data to validate.
`json_schema`	The schema to use to validate the data.
`raise_err`	`RAISE_NONE` — Do not raise an error for invalid schemas. `RAISE_ERROR` — Raise an error for invalid schemas.

If the schema is valid, the SCHEMA_VALID constant, 1, is returned. If the schema is not valid, the SCHEMA_INVALID constant, 0, is returned, unless the raise_err value is RAISE_ERROR, in which case an error is raised.

106.3.4 IS_VALID Procedure

This procedure checks the validity of JSON data for a specified schema.

See Also:

Oracle Database JSON Developer’s Guide

Syntax

PROCEDURE IS_VALID(
   json_data   IN  JSON,
   json_schema IN  JSON,
   result      OUT BOOLEAN,
   errors      OUT JSON);

Parameters

Table 106-5 IS_VALID Procedure Parameters

Parameter	Description
`json_data`	The JSON data to validate.
`json_schema`	The schema to use to validate the data.
`result`	The result of the validation, which is `TRUE` if the JSON data is valid and `FALSE` if not.
`errors`	A list of error messages that indicate why the JSON data was found invalid when validated against the specified schema.

106.3.5 VALIDATE_REPORT Function

This function reads the error report from the result of a schema validation.

See Also:

Oracle Database JSON Developer’s Guide

Syntax

FUNCTION VALIDATE_REPORT(
   json_data   IN   VARCHAR2,
   json_schema IN   VARCHAR2)
RETURN JSON;

Parameters

Table 106-6 VALIDATE_REPORT Function Parameters

Parameter	Description
`json_data`	The JSON data to validate.
`json_schema`	The schema to use to validate the data.