manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc

//
// 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.
//

=== Extend an existing schema

==== When a extension is needed?

Apache Unomi provides predefined schemas to validate some known events such as a view event.

The Apache Unomi JSON schemas are designed to consider invalid any properties which are not defined in the JSON schema.
So if an unknown property is part of the event, the event will be considered as invalid.

This means that if your events include additional properties, you will need extensions to describe these.

==== Understanding how extensions are merged in unomi

An extension schema is a JSON schema whose id will be overridden and be defined by a keyword named *extends* in the *self* part of the extension.

When sending an extension through the API, it will be persisted in Elasticsearch then will be merged to the targeted schema.

What does “merge a schema” mean?
The merge will simply add in the *allOf* keyword of the targeted schema a reference to the extensions.
It means that to be valid, an event should be valid against the base schema and against the ones added in the *allOf*.

Example of an extension to allow to add a new property in the view event properties:

[source]
----
{
    "$id": "https://vendor.test.com/schemas/json/events/dummy/extension/1-0-0",
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "self":{
        "vendor":"com.vendor.test",
        "name":"dummyExtension",
        "format":"jsonschema",
        "extends": "https://unomi.apache.org/schemas/json/events/view/properties/1-0-0",
        "version":"1-0-0"
    },
    "title": "DummyEventExtension",
    "type": "object",
    "properties": {
        "myNewProp": {
            "type": "string"
        }
    }
}
----

When validating the events of type view, the extension will be added to the schema with the id *\https://unomi.apache.org/schemas/json/events/view/properties/1-0-0* like the following:

[source]
----
"allOf": [{
    "$ref": "https://vendor.test.com/schemas/json/events/dummy/extension/1-0-0"
}]
----

With this extension the property *myNewProp* can now be added to the event.

[source]
----
…
"properties": {
    "myNewProp" : "newValue"
},
…
----

Process when adding extension:

image::process-creation-extension.png[pdfwidth=35%,align=center]

==== How to add an extension through the API

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 `POST {{url}}/cxs/jsonSchema` with the JSON schema in the payload of the request, the extension will be persisted and will be merged to the targeted schema.