Author: shuber
Date: Tue Apr 18 08:34:09 2023
New Revision: 1909211
URL: http://svn.apache.org/viewvc?rev=1909211&view=rev
Log:
Site checkin for project Apache Unomi :: Root Project
Removed:
unomi/website/manual/2_2_x/
Modified:
unomi/website/manual/latest/index.html
Modified: unomi/website/manual/latest/index.html
URL:
http://svn.apache.org/viewvc/unomi/website/manual/latest/index.html?rev=1909211&r1=1909210&r2=1909211&view=diff
==============================================================================
--- unomi/website/manual/latest/index.html (original)
+++ unomi/website/manual/latest/index.html Tue Apr 18 08:34:09 2023
@@ -138,11 +138,17 @@
<li><a href="#_details_on_invalid_events">5.2.6. Details on invalid
events</a></li>
</ul>
</li>
-<li><a href="#_extend_an_existing_schema">5.3. Extend an existing schema</a>
+<li><a href="#_develop_with_unomi_and_json_schemas">5.3. Develop with Unomi
and JSON Schemas</a>
<ul class="sectlevel3">
-<li><a href="#_when_a_extension_is_needed">5.3.1. When a extension is
needed?</a></li>
-<li><a href="#_understanding_how_extensions_are_merged_in_unomi">5.3.2.
Understanding how extensions are merged in unomi</a></li>
-<li><a href="#_how_to_add_an_extension_through_the_api">5.3.3. How to add an
extension through the API</a></li>
+<li><a href="#_logs_in_debug_mode">5.3.1. Logs in debug mode</a></li>
+<li><a href="#_validateevent_endpoint">5.3.2. validateEvent endpoint</a></li>
+</ul>
+</li>
+<li><a href="#_extend_an_existing_schema">5.4. Extend an existing schema</a>
+<ul class="sectlevel3">
+<li><a href="#_when_a_extension_is_needed">5.4.1. When a extension is
needed?</a></li>
+<li><a href="#_understanding_how_extensions_are_merged_in_unomi">5.4.2.
Understanding how extensions are merged in unomi</a></li>
+<li><a href="#_how_to_add_an_extension_through_the_api">5.4.3. How to add an
extension through the API</a></li>
</ul>
</li>
</ul>
@@ -3732,8 +3738,23 @@ If the JSON schema exists it will be upd
<div class="sect3">
<h4 id="_details_on_invalid_events">5.2.6. Details on invalid events</h4>
<div class="paragraph">
-<p>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.
+<p>If itâs an event which is incorrect the server will continue to process
the request but will exclude the invalid events.</p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_develop_with_unomi_and_json_schemas">5.3. Develop with Unomi and JSON
Schemas</h3>
+<div class="paragraph">
+<p>Schemas can be complex to develop, and sometimes, understanding why an
event is rejected can be challenging.</p>
+</div>
+<div class="paragraph">
+<p>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).</p>
+</div>
+<div class="sect3">
+<h4 id="_logs_in_debug_mode">5.3.1. Logs in debug mode</h4>
+<div class="paragraph">
+<p>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:</p>
</div>
<div class="listingblock">
@@ -3741,12 +3762,70 @@ You can set the log level of the class v
<pre class="highlight"><code>log:set DEBUG
org.apache.unomi.schema.impl.SchemaServiceImpl</code></pre>
</div>
</div>
+<div class="paragraph">
+<p>Doing so will output logs similar to this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>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</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_validateevent_endpoint">5.3.2. validateEvent endpoint</h4>
+<div class="paragraph">
+<p>A dedicated Admin endpoint (requires authentication), accessible at:
<code>cxs/jsonSchema/validateEvent</code>, was created to validate events
against JSON Schemas loaded in Apache Unomi.</p>
+</div>
+<div class="paragraph">
+<p>For example, sending an event not matching a schema:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>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"
+ }
+}'</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Would return the following:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>Request rejected by the server because: Unable to
validate event: Schema not found for event type: no-event</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>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:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>[
+ {
+ "error": "There are unevaluated properties at following paths
$.source.scopee"
+ }
+]</code></pre>
+</div>
+</div>
</div>
</div>
<div class="sect2">
-<h3 id="_extend_an_existing_schema">5.3. Extend an existing schema</h3>
+<h3 id="_extend_an_existing_schema">5.4. Extend an existing schema</h3>
<div class="sect3">
-<h4 id="_when_a_extension_is_needed">5.3.1. When a extension is needed?</h4>
+<h4 id="_when_a_extension_is_needed">5.4.1. When a extension is needed?</h4>
<div class="paragraph">
<p>Apache Unomi provides predefined schemas to validate some known events such
as a view event.</p>
</div>
@@ -3759,7 +3838,7 @@ So if an unknown property is part of the
</div>
</div>
<div class="sect3">
-<h4 id="_understanding_how_extensions_are_merged_in_unomi">5.3.2.
Understanding how extensions are merged in unomi</h4>
+<h4 id="_understanding_how_extensions_are_merged_in_unomi">5.4.2.
Understanding how extensions are merged in unomi</h4>
<div class="paragraph">
<p>An extension schema is a JSON schema whose id will be overridden and be
defined by a keyword named <strong>extends</strong> in the
<strong>self</strong> part of the extension.</p>
</div>
@@ -3828,7 +3907,7 @@ It means that to be valid, an event shou
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_add_an_extension_through_the_api">5.3.3. How to add an
extension through the API</h4>
+<h4 id="_how_to_add_an_extension_through_the_api">5.4.3. How to add an
extension through the API</h4>
<div class="paragraph">
<p>Since an extension is also a JSON schema, it is possible to add extensions
by calling the endpoint to add a JSON schema.
By calling <code>POST {{url}}/cxs/jsonSchema</code> with the JSON schema in
the payload of the request, the extension will be persisted and will be merged
to the targeted schema.</p>
@@ -11326,7 +11405,7 @@ They allow to modify an item, that would
</div>
<div id="footer">
<div id="footer-text">
-Last updated 2023-03-31 14:32:13 +0200
+Last updated 2023-01-23 14:17:56 +0100
</div>
</div>
</body>
