Why JSON Schema support is needed?

APEX PDP uses AVRO library to perform JSON encoding and decoding to serialize/deserialize the data it consumes. When doing so, it attempts to ensure that the JSON data conforms to the AVRO Schema provided.
In an event that triggers a policy, there could be some fields that are optional, the fields which are not always present depending on the use case.
Avro fails to handle this, and there is no way in APEX-PDP to handle events with optional fields today.

Avro has the concept of union and default, but this doesn't work while decoding a JSON event when the field is missing.
There is an open bug/missing feature in the Avro JSON Decoder library which cannot apply defaults to missing fields, it enforces it instead: https://issues.apache.org/jira/browse/AVRO-2890.

Hence, adding JSON Schema support in addition to Avro support in APEX-PDP can be beneficial.
In addition to the support for optional fields, JSON Schema support can help in writing the schema and using the fields in the logic itself much more simple and straightforward.

Note: Avro schema will continue to be supported in APEX-PDP, JSON Schema support will come in addition to Avro support.

What are the potential solutions?

The JSON Schema validators available today are listed here: https://json-schema.org/implementations.html#validator-java

Medeia-validator seems to be the sensible choice to be used for the JSON Schema support. Medeia-validator is already part of the policy-common/policy-models modules.
medeia-validator-gson supports GSON under the hood making it the right choice. The performance of this library also seems to be better comparitively as per the analysis here https://github.com/worldturner/medeia-validator#performance

What are the expected changes?

1) In the codebase

A new maven module plugins-context-schema-json will be added here: https://github.com/onap/policy-apex-pdp/tree/master/plugins/plugins-context/plugins-context-schema
This module will most likely make use of medeia-validator-gson library to encode and decode Json events.
Note: If using medeia-validator-gson library, there shouldn't be much need for implementation specific mapper classes as it uses GSON under the hood and the conversion is more straightforward.

2) In the Policy config file (ApexConfig.json)

Add the below part to the schemaParameters just like how Avro is specified today.

"Json": {
   "parameterClassName": "org.onap.policy.apex.plugins.context.schema.json.JsonSchemaHelperParameters"
}

3) In the Policy command file (*.apex)

Use Json instead of Avro. For e.g.,

schema create name=CDSRequestCommonHeaderType flavour=Json schema=LS
#MACROFILE:"src/main/resources/schemas/CDSRequestCommonHeaderType.json"
LE

4) Create the schema file containing the JsonSchema.

Many online tools are available to easily create JSON Schema from JSON event: https://extendsclass.com/json-schema-validator.html
For e.g., CDSRequestCommonHeaderType.json is the file containing the corresponding JsonSchema definition (JSON Schema draft 4 and 7 versions are shown below - both should work fine).

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "originatorId": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "subRequestId": {
      "type": "string"
    }
  },
  "required": [
    "originatorId",
    "requestId",
    "subRequestId"
  ]
}

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Root",
  "type": "object",
  "required": [
    "requestId",
    "subRequestId",
    "originatorId"
  ],
  "properties": {
    "requestId": {
      "$id": "#root/requestId",
      "title": "Requestid",
      "type": "string",
      "default": "",
      "examples": [
        "123456-1000"
      ],
      "pattern": "^.*$"
    },
    "subRequestId": {
      "$id": "#root/subRequestId",
      "title": "Subrequestid",
      "type": "string",
      "default": "",
      "examples": [
        "sub-123456-1000"
      ],
      "pattern": "^.*$"
    },
    "originatorId": {
      "$id": "#root/originatorId",
      "title": "Originatorid",
      "type": "string",
      "default": "",
      "examples": [
        "sdnc"
      ],
      "pattern": "^.*$"
    }
  }
}

Note: If a field is optional, then do not mention it in the required fields list.

5) In the logic file

The extra complexity of using "_DoT_" instead of ".", "_DasH_" instead of "-" and "_ColoN_" instead of ":" will be removed and the field names can be directly used.
createNewInstance and createNewSubInstance methods will probably not be needed when populating fields that are defined using JSON Schema. HashMap, ArrayList etc can directly be created and used as these can be mapped straightaway using the JsonSchema validator.

For e.g., with Avro, to populate the fields, the below lines are needed:

var payloadEntry = executor.subject.getOutFieldSchemaHelper("payload").createNewSubInstance("CDSRequestPayloadEntry");
payloadEntry.put("create_DasH_subscription_DasH_properties", payloadProperties)
var payload = executor.subject.getOutFieldSchemaHelper("payload").createNewInstance();
payload.put("create_DasH_subscription_DasH_request", payloadEntry);

By using JSON Schema, this could be replaced as below:

var payloadEntry = new java.util.HashMap();
payloadEntry.put("create-subscription-properties", payloadProperties)
var payload = new java.util.HashMap();
payload.put("create-subscription-request", payloadEntry);

Test Plan

The test plan for validating the JSON Schema Support in any example policy is attached here - APEX_PDP_JSON_Schema_Support_Test_Plan.xlsx

Summary

JsonSchema support in APEX-PDP has the following advantages:

Support for optional fields in events enabling APEX-PDP for more use cases.
No naming restrictions unlike Avro and flexibility in usage.

ONAP Wiki

JSON Schema support in APEX-PDP