This is an automated email from the ASF dual-hosted git repository.
fgerthoffert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new ecf29a4f1 [UNOMI-763] - Addided validateEvent documentation (#610)
ecf29a4f1 is described below
commit ecf29a4f1a8bc7934c110959baddfaca96954d7e
Author: Francois G <fgerthoff...@jahia.com>
AuthorDate: Tue Apr 18 08:11:12 2023 +0200
[UNOMI-763] - Addided validateEvent documentation (#610)
---
.../main/asciidoc/jsonSchema/json-schema-api.adoc | 7 --
.../asciidoc/jsonSchema/json-schema-develop.adoc | 81 ++++++++++++++++++++++
.../src/main/asciidoc/jsonSchema/json-schema.adoc | 2 +
3 files changed, 83 insertions(+), 7 deletions(-)
diff --git a/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc
b/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc
index bec18024b..d489912b1 100644
--- a/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc
+++ b/manual/src/main/asciidoc/jsonSchema/json-schema-api.adoc
@@ -129,10 +129,3 @@ 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 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]
-----
-log:set DEBUG org.apache.unomi.schema.impl.SchemaServiceImpl
-----
diff --git a/manual/src/main/asciidoc/jsonSchema/json-schema-develop.adoc
b/manual/src/main/asciidoc/jsonSchema/json-schema-develop.adoc
new file mode 100644
index 000000000..5cfd5fb9d
--- /dev/null
+++ b/manual/src/main/asciidoc/jsonSchema/json-schema-develop.adoc
@@ -0,0 +1,81 @@
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+=== Develop with Unomi and JSON Schemas
+
+Schemas can be complex to develop, and sometimes, understanding why an event
is rejected can be challenging.
+
+This section of the documentation defails mechanisms put in place to
facilitate the development when working around JSON Schemas (when creating a
new schema, when
+modifying an existing event, ...etc).
+
+==== Logs in debug mode
+
+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]
+----
+log:set DEBUG org.apache.unomi.schema.impl.SchemaServiceImpl
+----
+
+Doing so will output logs similar to this:
+
+[source]
+----
+08:55:28.128 DEBUG [qtp1422628821-128] Schema validation found 2 errors while
validating against schema:
https://unomi.apache.org/schemas/json/events/view/1-0-0
+08:55:28.138 DEBUG [qtp1422628821-128] Validation error: There are unevaluated
properties at following paths $.source.properties
+08:55:28.140 DEBUG [qtp1422628821-128] Validation error: There are unevaluated
properties at following paths $.source.itemId, $.source.itemType,
$.source.scope, $.source.properties
+08:55:28.142 ERROR [qtp1422628821-128] An event was rejected - switch to DEBUG
log level for more information
+----
+
+==== validateEvent endpoint
+
+A dedicated Admin endpoint (requires authentication), accessible at:
`cxs/jsonSchema/validateEvent`, was created to validate events against JSON
Schemas loaded in Apache Unomi.
+
+For example, sending an event not matching a schema:
+[source]
+----
+curl --request POST \
+ --url http://localhost:8181/cxs/jsonSchema/validateEvent \
+ --user karaf:karaf \
+ --header 'Authorization: Basic a2FyYWY6amN1c3RvbWVyUEA1NQ==' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "eventType": "no-event",
+ "scope": "unknown_scope",
+ "properties": {
+ "workspace": "no_workspace",
+ "path": "some/path"
+ }
+}'
+----
+
+Would return the following:
+
+[source]
+----
+Request rejected by the server because: Unable to validate event: Schema not
found for event type: no-event
+----
+
+And if we were to submit a valid event type but make a typo in one of the
properties name, the endpoint will point us
+towards the incorrect property:
+
+[source]
+----
+[
+ {
+ "error": "There are unevaluated properties at following paths
$.source.scopee"
+ }
+]
+----
diff --git a/manual/src/main/asciidoc/jsonSchema/json-schema.adoc
b/manual/src/main/asciidoc/jsonSchema/json-schema.adoc
index 352c27ebe..8a4986fa5 100644
--- a/manual/src/main/asciidoc/jsonSchema/json-schema.adoc
+++ b/manual/src/main/asciidoc/jsonSchema/json-schema.adoc
@@ -15,4 +15,6 @@ include::introduction.adoc[]
include::json-schema-api.adoc[]
+include::json-schema-develop.adoc[]
+
include::extend-an-existing-schema.adoc[]
