Table of Contents
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.
...
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.
...
| Code Block | ||
|---|---|---|
| ||
"Json": {
"parameterClassName": "org.onap.policy.apex.plugins.context.schema.json.JsonSchemaHelperParameters"
} |
...
3) In the Policy command file (*.apex)
Use Use Json instead of Avro. For e.g.,
schema create
| Code Block | ||
|---|---|---|
| ||
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 Many online tools are available to easily create JSON Schema from JSON event: https://extendsclass.com/json-schema-validator.html )
For 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).
{
| Code Block | ||
|---|---|---|
| ||
{ "$schema": "http://json-schema.org/draft-04/schema#", |
...
"type": "object", |
...
"properties": |
...
{ "originatorId": |
...
{ "type": "string" |
...
}, "requestId": |
...
{ "type": "string" |
...
}, "subRequestId": |
...
{ "type": "string" |
...
} }, "required": |
...
[ "originatorId", |
...
"requestId", |
...
"subRequestId" |
...
]
} |
| Code Block | ||
|---|---|---|
| ||
{ "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 =
| Code Block | ||
|---|---|---|
| ||
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); |
This By using JSON Schema, this could be replaced with
var payloadEntry = new as below:
| Code Block | ||
|---|---|---|
| ||
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:1)
- Support for optional fields in events enabling APEX-PDP for more use cases.
...
- No naming restrictions unlike Avro and flexibility in usage.