This is an automated email from the ASF dual-hosted git repository. jsinovassinnaik pushed a commit to branch UNOMI-625-add-json-schema-documentation in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/UNOMI-625-add-json-schema-documentation by this push: new 59809ec8c feedbacks 59809ec8c is described below commit 59809ec8c13f12243c8a53b5018ae61ccd8da089 Author: jsinovassin <jsinovassinn...@jahia.com> AuthorDate: Fri Jul 8 16:43:16 2022 +0200 feedbacks --- .../src/main/asciidoc/jsonSchema/introduction.adoc | 20 ++++++++++---------- .../main/asciidoc/jsonSchema/json-schema-api.adoc | 4 ++-- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/manual/src/main/asciidoc/jsonSchema/introduction.adoc b/manual/src/main/asciidoc/jsonSchema/introduction.adoc index 4a233cfdf..ce4848000 100644 --- a/manual/src/main/asciidoc/jsonSchema/introduction.adoc +++ b/manual/src/main/asciidoc/jsonSchema/introduction.adoc @@ -20,7 +20,7 @@ https://json-schema.org/specification.html[JSON Schema] is a powerful standard f Described as a JSON object, a JSON schema file contains format, types, patterns, and more. Used against JSON data, a JSON schema validates that the data is compatible with the specified schema. -Example of a basic JSON schema that validate that the path property is a string property: +Example of a basic JSON schema that validates that the path property is a string property: [source] ---- @@ -170,7 +170,7 @@ Invalid JSON: It’s also possible to use a reference *$ref* in the *allOf* keyword to reference another schema. -In UNOMI, there is an example of using *$ref* in the *allOf* keyword to validate the properties which are defined in the event schema. +In Unomi, there is an example of using *$ref* in the *allOf* keyword to validate the properties which are defined in the event schema. This schema contains properties common to all events. It’s done in the the view event schema. The file can be found on github: https://github.com/apache/unomi/blob/master/extensions/json-schema/services/src/main/resources/META-INF/cxs/schemas/events/view/view.json#L13[view.json] @@ -178,7 +178,7 @@ More details about allOf can be found in the specifications: https://json-schema ===== unevaluatedProperties keyword -The *unevaluatedProperties* keyword is useful for schema composition. +The *unevaluatedProperties* keyword is useful for schema composition as well as enforcing stricter schemas. This keyword is similar to *additionalProperties* except that it can recognize properties declared in sub schemas. When setting the *unevaluatedProperties* value to *false*, the properties which are not present in the properties part and are not present in the sub schemas will be considered as invalid. @@ -235,13 +235,13 @@ With the following data, the validation will fail because the property *myNewPro ==== How are JSON Schema used in Unomi -JSON Schema is used in UNOMI to validate the data coming from the two public endpoints */contextRequest* and */eventCollector*. +JSON Schema is used in Unomi to validate the data coming from the two public endpoints */contextRequest* and */eventCollector*. Both endpoints have a custom deserializer which will begin by validating the payload of the request, then will filter invalid events present in this payload. If an event is not valid it will not be processed by the system. The internal events are not validated by JSON schema as they are not sent through the public endpoints. -In UNOMI, each event type must have an associated JSON schema. -To validate an event, UNOMI will search for a schema in which the target of the schema is *events*, and with the name of the schema matching the event type. +In Unomi, each event type must have an associated JSON schema. +To validate an event, Unomi will search for a schema in which the target of the schema is *events*, and with the name of the schema matching the event type. A custom keyword named *self* has to be present in the JSON schemas to store the information related to each schema. The following example is the *self* part of the view event JSON schema. @@ -262,17 +262,17 @@ Having the target set to *events* and the name set to *view*, this schema will b Link to the schema on github: https://github.com/apache/unomi/blob/master/extensions/json-schema/services/src/main/resources/META-INF/cxs/schemas/events/view/view.json[view.json]. -A set of predefined schema are present in UNOMI, these schemas can be found under the folder : https://github.com/apache/unomi/tree/master/extensions/json-schema/services/src/main/resources/META-INF/cxs/schemas[extensions/json-schema/services/src/main/resources/META-INF/cxs/schemas]. +A set of predefined schema are present in Unomi, these schemas can be found under the folder : https://github.com/apache/unomi/tree/master/extensions/json-schema/services/src/main/resources/META-INF/cxs/schemas[extensions/json-schema/services/src/main/resources/META-INF/cxs/schemas]. These schemas will be loaded in memory at startup. Each schema where the *target* value is set to *events*, will be used to validate events. The others are simply used as part of JSON schema or can be used in additional JSON schemas. -It’s possible to add JSON schema to validate your own event by using the API, the explanations to manage JSON schema through the API are +It’s possible to add JSON schemas to validate your own event by using the API, the explanations to manage JSON schema through the API are in the <<Create / update a JSON schema to validate an event, Create / update a JSON schema to validate an event>> section. -Contrary to the predefined schemas, the schemas added through the API will be persisted in elasticsearch in the jsonSchema index. -Schemas persisted in Elasticsearch do not need a restart of the platform to reflect changes. +Contrary to the predefined schemas, the schemas added through the API will be persisted in Elasticsearch in the jsonSchema index. +Schemas persisted in Elasticsearch do not require a restart of the platform to reflect changes. Process of creation of schemas: diff --git a/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc b/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc index f9fcb1cb9..bec18024b 100644 --- a/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc +++ b/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc @@ -14,7 +14,7 @@ === JSON schema API -The JSON schema endpoints are private, so the user has to be authenticated to manage the JSON schema in UNOMI. +The JSON schema endpoints are private, so the user has to be authenticated to manage the JSON schema in Unomi. ==== List existing schemas @@ -129,7 +129,7 @@ When calling an endpoint with invalid data, such as an invalid value for the *se ==== Details on invalid events If it’s an event which is incorrect the server will continue to process the request but will exclude the invalid events. -Running Apache Unomi with the Debug flag will add to the logs the reason why events are rejected. +Running Apache Unomi with the logs in debug level will add to the logs the reason why events are rejected. You can set the log level of the class validating the events to debug by using the following karaf command: [source]