You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@unomi.apache.org by sh...@apache.org on 2026/01/15 17:15:41 UTC

(unomi) branch unomi-3-dev updated: UNOMI-882 Update documentation for Apache Unomi 3.x

This is an automated email from the ASF dual-hosted git repository.

shuber pushed a commit to branch unomi-3-dev
in repository https://gitbox.apache.org/repos/asf/unomi.git


The following commit(s) were added to refs/heads/unomi-3-dev by this push:
     new f7d42a9aa UNOMI-882 Update documentation for Apache Unomi 3.x
f7d42a9aa is described below

commit f7d42a9aabf3ba5afdf3d434873745372ea3b6c4
Author: Serge Huber <sh...@jahia.com>
AuthorDate: Thu Jan 15 18:15:38 2026 +0100

    UNOMI-882 Update documentation for Apache Unomi 3.x
    
    - Changed document type from article to book in pom.xml.
    - Added a foreword section to provide an overview of Apache Unomi 3.x.
    - Enhanced the Quick Start guide with additional steps for creating a tenant and retrieving context.
    - Updated various sections to include tenant authentication examples and improved clarity on API usage.
    - Added new migration guides for Elasticsearch 7 to 9 and Elasticsearch to OpenSearch.
    - Introduced new property types and JSON schema documentation.
    - Improved consistency in references and formatting across multiple Asciidoc files.
---
 manual/pom.xml                                     |    2 +-
 manual/src/main/asciidoc/5-min-quickstart.adoc     |   46 +-
 .../src/main/asciidoc/building-and-deploying.adoc  |    4 +-
 manual/src/main/asciidoc/builtin-action-types.adoc |    1 +
 .../src/main/asciidoc/builtin-condition-types.adoc |    1 +
 manual/src/main/asciidoc/builtin-event-types.adoc  |    1 +
 manual/src/main/asciidoc/configuration.adoc        |   12 +-
 .../src/main/asciidoc/connectors/connectors.adoc   |    2 +-
 .../asciidoc/connectors/salesforce-connector.adoc  |    3 +-
 manual/src/main/asciidoc/consent-api.adoc          |    1 +
 manual/src/main/asciidoc/data-structures.adoc      |    4 +-
 manual/src/main/asciidoc/datamodel.adoc            |    8 +-
 manual/src/main/asciidoc/event-processing.adoc     |    4 +-
 manual/src/main/asciidoc/foreword.adoc             |   26 +
 manual/src/main/asciidoc/getting-started.adoc      |    8 +-
 manual/src/main/asciidoc/graphql-examples.adoc     |    2 +-
 .../main/asciidoc/how-profile-tracking-works.adoc  |    1 +
 manual/src/main/asciidoc/index.adoc                |   48 +-
 .../main/asciidoc/javascript-tracker-guide.adoc    | 1260 ++++++++++++++++
 .../jsonSchema/extend-an-existing-schema.adoc      |    1 +
 .../src/main/asciidoc/jsonSchema/introduction.adoc |    2 +-
 .../asciidoc/jsonSchema/json-schema-develop.adoc   |    2 +-
 .../asciidoc/migrations/migrate-1.4-to-1.5.adoc    |    8 +-
 .../asciidoc/migrations/migrate-1.6-to-2.0.adoc    |    4 +-
 .../asciidoc/migrations/migrate-2.x-to-3.0.adoc    |    6 +-
 .../migrate-elasticsearch-to-opensearch.adoc       |   35 +-
 .../{ => migrations}/migrate-es7-to-es9.adoc       |   17 +-
 .../src/main/asciidoc/migrations/migrations.adoc   |    2 +
 manual/src/main/asciidoc/multitenancy.adoc         |  122 +-
 manual/src/main/asciidoc/patches.adoc              |    1 +
 manual/src/main/asciidoc/privacy.adoc              |    2 +-
 manual/src/main/asciidoc/property-types.adoc       | 1561 ++++++++++++++++++++
 .../main/asciidoc/queries-and-aggregations.adoc    |   14 +-
 manual/src/main/asciidoc/recipes.adoc              |   16 +-
 manual/src/main/asciidoc/request-examples.adoc     |   45 +-
 manual/src/main/asciidoc/samples/login-sample.adoc |    1 +
 manual/src/main/asciidoc/samples/samples.adoc      |    5 +-
 .../src/main/asciidoc/samples/twitter-sample.adoc  |    1 +
 manual/src/main/asciidoc/security.adoc             |    4 +-
 manual/src/main/asciidoc/useful-unomi-urls.adoc    |    1 +
 manual/src/main/asciidoc/web-tracker.adoc          |    3 +-
 manual/src/main/asciidoc/whats-new.adoc            |    6 +-
 manual/src/main/asciidoc/writing-plugins.adoc      |   14 +-
 43 files changed, 3155 insertions(+), 152 deletions(-)

diff --git a/manual/pom.xml b/manual/pom.xml
index cc380ee51..0cd12bc70 100644
--- a/manual/pom.xml
+++ b/manual/pom.xml
@@ -79,7 +79,7 @@
                             <outputDirectory>${doc.output.html}</outputDirectory>
                             <preserveDirectories>true</preserveDirectories>
                             <backend>html5</backend>
-                            <doctype>article</doctype>
+                            <doctype>book</doctype>
                             <attributes>
                                 <toc />
                                 <linkcss>true</linkcss>
diff --git a/manual/src/main/asciidoc/5-min-quickstart.adoc b/manual/src/main/asciidoc/5-min-quickstart.adoc
index 62c562851..420095493 100644
--- a/manual/src/main/asciidoc/5-min-quickstart.adoc
+++ b/manual/src/main/asciidoc/5-min-quickstart.adoc
@@ -12,6 +12,7 @@
 // limitations under the License.
 //
 
+[[_five_minutes_quickstart]]
 === Quick start with Docker
 
 Begin by creating a `docker-compose.yml` file. You can choose between ElasticSearch or OpenSearch:
@@ -99,7 +100,7 @@ Try accessing https://localhost:9443/cxs/cluster with username/password: karaf/k
 
 ==== Option 1: Using ElasticSearch
 
-1) Install JDK 17 and make sure you set the JAVA_HOME variable (see our <<JDK compatibility,Getting Started>> guide for more information on JDK compatibility)
+1) Install JDK 17 and make sure you set the JAVA_HOME variable (see our <<_jdk_compatibility,Getting Started>> guide for more information on JDK compatibility)
 
 2) Download ElasticSearch here : https://www.elastic.co/downloads/past-releases/elasticsearch-9-2-1 (please *make sure* you use the proper version : 9.2.1)
 
@@ -148,14 +149,51 @@ which determines which set of features and bundles are installed and started. A
 
 9) Try accessing https://localhost:9443/cxs/cluster with username/password: `karaf/karaf` . You might get a certificate warning in your browser, just accept it despite the warning it is safe.
 
-10) Request your first context by simply accessing : http://localhost:8181/cxs/context.js?sessionId=1234
+10) Create a tenant that will own all your data:
 
-11) If something goes wrong, you should check the logs in `./data/log/karaf.log`. If you get errors on the search engine,
+[source,bash]
+----
+curl -X POST http://localhost:8181/cxs/tenants \
+  --user karaf:karaf \
+  -H "Content-Type: application/json" \
+  -d '{
+    "requestedId": "default",
+    "properties": {
+      "name": "Default Tenant",
+      "description": "Default tenant for quick start"
+    }
+  }'
+----
+
+Save the API keys from the response - you'll need them for API calls.
+
+11) Request your first context:
+
+[source,bash]
+----
+curl -X POST http://localhost:8181/cxs/context.json?sessionId=1234 \
+  -H "Content-Type: application/json" \
+  -H "X-Unomi-Api-Key: <YOUR_PUBLIC_API_KEY>" \
+  -d '{
+    "source": {
+      "itemId": "homepage",
+      "itemType": "page",
+      "scope": "default"
+    }
+  }'
+----
+
+Or access it directly in a browser (requires API key in header):
+`http://localhost:8181/cxs/context.js?sessionId=1234`
+
+NOTE: For the context request to work, you'll need to include the public API key from step 10 in the request header: `X-Unomi-Api-Key: <YOUR_PUBLIC_API_KEY>`
+
+12) If something goes wrong, you should check the logs in `./data/log/karaf.log`. If you get errors on the search engine,
 make sure you are using the proper version.
 
 Next steps:
 
-- Trying our integration <<Samples,samples page>>
+- Trying our integration <<_samples,samples page>>
 
 Note: When using OpenSearch, make sure to:
 - Set up proper SSL certificates or disable SSL verification for development
diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc b/manual/src/main/asciidoc/building-and-deploying.adoc
index b36c70b28..acb54aa16 100644
--- a/manual/src/main/asciidoc/building-and-deploying.adoc
+++ b/manual/src/main/asciidoc/building-and-deploying.adoc
@@ -12,11 +12,12 @@
 // limitations under the License.
 //
 
+[[_building]]
 === Building
 
 Apache Unomi 3.x provides a convenient `build.sh` script that simplifies the build process with
 enhanced error handling, preflight validation, and deployment options. See the
-<<Using the build.sh script>> section below for details. Alternatively, you can build using Maven
+<<_using_the_build_script,Using the build.sh script>> section below for details. Alternatively, you can build using Maven
 directly as described in this section.
 
 ==== Initial Setup
@@ -71,6 +72,7 @@ TIP: On a non-English Windows env, the Asciidoctor Maven Plugin may fail to
 +
 . The distributions will be available under "package/target" directory.
 
+[[_using_the_build_script]]
 ==== Using the build.sh script
 
 Apache Unomi 3.x provides a unified `build.sh` script that simplifies the build, deployment, and execution process.
diff --git a/manual/src/main/asciidoc/builtin-action-types.adoc b/manual/src/main/asciidoc/builtin-action-types.adoc
index 4543420b6..7163fc6da 100644
--- a/manual/src/main/asciidoc/builtin-action-types.adoc
+++ b/manual/src/main/asciidoc/builtin-action-types.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_builtin_action_types]]
 === Built-in action types
 
 Unomi comes with quite a lot of built-in action types. Instead of detailing them one by one you will find here an overview of
diff --git a/manual/src/main/asciidoc/builtin-condition-types.adoc b/manual/src/main/asciidoc/builtin-condition-types.adoc
index 64a24b87f..247d5252c 100644
--- a/manual/src/main/asciidoc/builtin-condition-types.adoc
+++ b/manual/src/main/asciidoc/builtin-condition-types.adoc
@@ -12,6 +12,7 @@
 // limitations under the License.
 //
 
+[[_builtin_condition_types]]
 === Built-in condition types
 
 Apache Unomi comes with an extensive collection of built-in condition types. Instead of detailing them one by one you will
diff --git a/manual/src/main/asciidoc/builtin-event-types.adoc b/manual/src/main/asciidoc/builtin-event-types.adoc
index ef9c2b3b8..74ddd7122 100644
--- a/manual/src/main/asciidoc/builtin-event-types.adoc
+++ b/manual/src/main/asciidoc/builtin-event-types.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_builtin_event_types]]
 === Built-in Event types
 
 Apache Unomi comes with built-in event types, which we describe below.
diff --git a/manual/src/main/asciidoc/configuration.adoc b/manual/src/main/asciidoc/configuration.adoc
index d0d95c9d6..b607854bb 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/asciidoc/configuration.adoc
@@ -961,7 +961,7 @@ by this action.
 When a profile merge is triggered, the following process takes place:
 
 [plantuml]
-....
+----
 @startuml
 title Apache Unomi Profile Merge Workflow
 
@@ -1010,14 +1010,14 @@ deactivate Action
 Event --> User: Event processed
 deactivate Event
 @enduml
-....
+----
 
 ==== Before and after a profile merge
 
 This diagram illustrates the state of profiles before and after a merge:
 
 [plantuml]
-....
+----
 @startuml
 title Before and After Profile Merge
 
@@ -1060,7 +1060,7 @@ package "After Merge" {
 PA ..> MP : becomes
 PB ..> AL : becomes alias for Master
 @enduml
-....
+----
 
 Starting from Unomi 2:
 
@@ -1100,7 +1100,7 @@ IMPORTANT: Never trigger profile merges from unauthenticated operations such as
 The following diagram highlights key security considerations:
 
 [plantuml]
-....
+----
 @startuml
 title Profile Merge Security Considerations
 
@@ -1134,7 +1134,7 @@ endif
 :Proceed with Profile Merge;
 stop
 @enduml
-....
+----
 
 Key security recommendations:
 
diff --git a/manual/src/main/asciidoc/connectors/connectors.adoc b/manual/src/main/asciidoc/connectors/connectors.adoc
index def921626..dc2d34961 100644
--- a/manual/src/main/asciidoc/connectors/connectors.adoc
+++ b/manual/src/main/asciidoc/connectors/connectors.adoc
@@ -15,7 +15,7 @@
 
 Apache Unomi provides the following connectors:
 
-* <<Salesforce Connector,Salesforce CRM connector>>
+* <<_salesforce_connector,Salesforce CRM connector>>
 
 ==== Call for contributors
 
diff --git a/manual/src/main/asciidoc/connectors/salesforce-connector.adoc b/manual/src/main/asciidoc/connectors/salesforce-connector.adoc
index afb732b3a..73998c96e 100644
--- a/manual/src/main/asciidoc/connectors/salesforce-connector.adoc
+++ b/manual/src/main/asciidoc/connectors/salesforce-connector.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_salesforce_connector]]
 === Salesforce Connector
 
 This connectors makes it possible to push and pull data to/from the Salesforce CRM. It can copy information between
@@ -112,7 +113,7 @@ Both URLs are password protected by the Apache Unomi (Karaf) password. You can f
 in the etc/users.properties file.
 
 You can now use the connectors's defined actions in rules to push or pull data to/from the Salesforce CRM. You can
-find more information about rules in the <<Data Model Overview,Data Model>> and the <<Getting started with Unomi,Getting Started>> pages.
+find more information about rules in the <<_data_model_overview,Data Model>> and the <<_getting_started_with_unomi,Getting Started>> pages.
 
 ==== Properties
 
diff --git a/manual/src/main/asciidoc/consent-api.adoc b/manual/src/main/asciidoc/consent-api.adoc
index 02657c232..4086ed7ab 100644
--- a/manual/src/main/asciidoc/consent-api.adoc
+++ b/manual/src/main/asciidoc/consent-api.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_consent_api]]
 === Consent API
 
 Starting with Apache Unomi 1.3, a new API for consent management is now available. This API
diff --git a/manual/src/main/asciidoc/data-structures.adoc b/manual/src/main/asciidoc/data-structures.adoc
index ce9a16ff4..0d4cf9a81 100644
--- a/manual/src/main/asciidoc/data-structures.adoc
+++ b/manual/src/main/asciidoc/data-structures.adoc
@@ -12,7 +12,7 @@
 // limitations under the License.
 //
 
-=== Core Data Structures Overview
+==== Core Data Structures Overview
 
 ==== Base Types
 
@@ -255,7 +255,7 @@ All these entities inherit from `MetadataItem` which provides:
 - Read-only protection
 - Version tracking
 
-=== Detailed Structure Definitions
+==== Detailed Structure Definitions
 
 The following sections provide detailed diagrams for each major component:
 
diff --git a/manual/src/main/asciidoc/datamodel.adoc b/manual/src/main/asciidoc/datamodel.adoc
index 9c4359b5c..88de04fad 100755
--- a/manual/src/main/asciidoc/datamodel.adoc
+++ b/manual/src/main/asciidoc/datamodel.adoc
@@ -12,6 +12,7 @@
 // limitations under the License.
 //
 
+[[_data_model_overview]]
 === Data Model Overview
 
 Apache Unomi gathers information about users actions, information that is processed and stored by Unomi services.
@@ -222,7 +223,7 @@ Inherits all the fields from: <<Item>>
 
 Event types are completely open, and any new event type will be accepted by Apache Unomi.
 
-Apache Unomi also comes with an extensive list of <<Built-in Event types,built-in event types>> you can find in the reference section of this manual.
+Apache Unomi also comes with an extensive list of <<_builtin_event_types,built-in event types>> you can find in the reference section of this manual.
 
 === Profile
 
@@ -612,6 +613,7 @@ The visitor’s location is also resolve based on the IP address that was used t
 }
 ----
 
+[[_segment]]
 === Segment
 
 Segments are used to group profiles together, and are based on conditions that are executed on profiles to determine
@@ -730,7 +732,7 @@ The result of a condition is always a boolean value of true or false.
 Apache Unomi provides quite a lot of built-in condition types, including boolean types that make it possible to compose conditions using operators such as `and`, `or` or `not`.
 Composition is an essential element of building more complex conditions.
 
-For a more complete list of available condition types, see the <<Built-in condition types>> reference section.
+For a more complete list of available condition types, see the <<_builtin_condition_types,Built-in condition types>> reference section.
 
 ==== Structure definition
 
@@ -875,7 +877,7 @@ calling web hooks, setting profile properties, extracting data from the incoming
 an IP address),  or even pulling and/or pushing data to third-party systems such as a CRM server.
 
 Apache Unomi also comes with built-in action types.
-You may find the list of built-in action types in the <<Built-in action types>> section.
+You may find the list of built-in action types in the <<_builtin_action_types,Built-in action types>> section.
 
 ==== Structure definition
 
diff --git a/manual/src/main/asciidoc/event-processing.adoc b/manual/src/main/asciidoc/event-processing.adoc
index b153446b9..84780aeaa 100644
--- a/manual/src/main/asciidoc/event-processing.adoc
+++ b/manual/src/main/asciidoc/event-processing.adoc
@@ -11,7 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
-=== Event Processing Architecture
+==== Event Processing Architecture
 
 [plantuml]
 ----
@@ -85,4 +85,4 @@ end note
 @enduml
 ----
 
-=== Overview 
\ No newline at end of file
+===== Overview 
\ No newline at end of file
diff --git a/manual/src/main/asciidoc/foreword.adoc b/manual/src/main/asciidoc/foreword.adoc
new file mode 100644
index 000000000..19fcbeec9
--- /dev/null
+++ b/manual/src/main/asciidoc/foreword.adoc
@@ -0,0 +1,26 @@
+//
+// 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.
+//
+
+[[_foreword]]
+== Foreword
+
+This documentation provides a comprehensive guide to Apache Unomi 3.x, a powerful and flexible Customer Data Platform (CDP) that enables organizations to collect, manage, and leverage customer data for personalization and marketing automation.
+
+Apache Unomi is built on open standards and provides a robust foundation for building customer-centric applications. Whether you're implementing personalization, running marketing campaigns, or building customer profiles, this documentation will help you understand and effectively use Apache Unomi's capabilities.
+
+This guide covers everything from getting started with your first installation to advanced topics like plugin development, migration strategies, and integration patterns. We recommend starting with the "Discover Unomi" section if you're new to the platform, and then exploring the specific topics that match your needs.
+
+The Apache Unomi community is committed to providing comprehensive, accurate, and up-to-date documentation. We welcome feedback and contributions to help improve this documentation for all users.
+
+Happy reading!
diff --git a/manual/src/main/asciidoc/getting-started.adoc b/manual/src/main/asciidoc/getting-started.adoc
index 3f59a7ea9..f6b6d09f1 100644
--- a/manual/src/main/asciidoc/getting-started.adoc
+++ b/manual/src/main/asciidoc/getting-started.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_getting_started_with_unomi]]
 === Getting started with Unomi
 
 We will first get you up and running with an example. We will then lift the corner of the cover somewhat and explain
@@ -21,6 +22,7 @@ in greater details what just happened.
 This document assumes working knowledge of https://git-scm.com/[git] to be able to retrieve the code for Unomi and the example.
 Additionally, you will require a working Java 17 or above install. Refer to http://www.oracle.com/technetwork/java/javase/[http://www.oracle.com/technetwork/java/javase/] for details on how to download and install Java SE 17 or greater.
 
+[[_jdk_compatibility]]
 ===== JDK compatibility
 
 Starting with Java 9, Oracle made some big changes to the Java platform releases. This is why Apache Unomi is focused on
@@ -50,8 +52,8 @@ Note for OpenSearch users:
 
 ===== Start Unomi
 
-Start Unomi according to the <<Five Minutes QuickStart,quick start with docker>> or by compiling using the
-<<Building,building instructions>>. Once you have Karaf running, you should wait until you see the following messages on the Karaf console:
+Start Unomi according to the <<_five_minutes_quickstart,quick start with docker>> or by compiling using the
+<<_building,building instructions>>. Once you have Karaf running, you should wait until you see the following messages on the Karaf console:
 
 [source]
 ----
@@ -72,5 +74,5 @@ This indicates that all the Unomi services are started and ready to react to req
 3. View the introduction page: `http://localhost:8181`
 
 Also now that your service is up and running you can go look at the
-<<Request examples,request examples>> to learn basic
+<<_request_examples,request examples>> to learn basic
 requests you can do once your server is up and running.
diff --git a/manual/src/main/asciidoc/graphql-examples.adoc b/manual/src/main/asciidoc/graphql-examples.adoc
index b4602288e..e5043052d 100644
--- a/manual/src/main/asciidoc/graphql-examples.adoc
+++ b/manual/src/main/asciidoc/graphql-examples.adoc
@@ -249,5 +249,5 @@ The response will show the result of the operation:
 
 ==== Where to go from here
 
-* You can find more <<Useful Apache Unomi URLs,useful Apache Unomi URLs>> that can be used in the same way as the above examples.
+* You can find more <<_useful_apache_unomi_urls,useful Apache Unomi URLs>> that can be used in the same way as the above examples.
 * Read https://graphql.org/learn/[GraphQL documentation] to learn more about GraphQL syntax.
diff --git a/manual/src/main/asciidoc/how-profile-tracking-works.adoc b/manual/src/main/asciidoc/how-profile-tracking-works.adoc
index 0296dd3e1..aa8597f5b 100644
--- a/manual/src/main/asciidoc/how-profile-tracking-works.adoc
+++ b/manual/src/main/asciidoc/how-profile-tracking-works.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_how_profile_tracking_works]]
 === How profile tracking works
 
 In this section you will learn how Apache Unomi keeps track of visitors.
diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc
index 375255aab..09a9d8843 100644
--- a/manual/src/main/asciidoc/index.adoc
+++ b/manual/src/main/asciidoc/index.adoc
@@ -12,9 +12,9 @@
 // limitations under the License.
 //
 
-= Apache Unomi 2.x - Documentation
+= Apache Unomi 3.x - Documentation
 Apache Software Foundation
-:doctype: article
+:doctype: book
 :toc: left
 :toclevels: 3
 :toc-position: left
@@ -24,23 +24,13 @@ Apache Software Foundation
 
 image::asf_logo_url.png[pdfwidth=35%,align=center]
 
+include::foreword.adoc[]
+
+[[_whats_new]]
 == What's new
 
 include::whats-new.adoc[]
 
-== Architecture Overview
-
-include::architecture.adoc[]
-
-=== Data Structures
-include::data-structures.adoc[]
-
-=== Event Processing Architecture
-include::event-processing.adoc[]
-
-=== Security Architecture
-include::security.adoc[]
-
 == Discover Unomi
 
 include::5-min-quickstart.adoc[]
@@ -55,28 +45,28 @@ include::recipes.adoc[]
 
 include::request-examples.adoc[]
 
+[[_configuration]]
 == Configuration
 
 include::configuration.adoc[]
 
+[[_json_schemas]]
 == JSON schemas
 
 include::jsonSchema/json-schema.adoc[]
 
+[[_graphql_api]]
 == GraphQL API
 
 include::graphql.adoc[]
 
 include::graphql-examples.adoc[]
 
+[[_migrations]]
 == Migrations
 
 include::migrations/migrations.adoc[]
 
-include::migrations/migrate-1.4-to-1.5.adoc[leveloffset=+1]
-
-include::migrations/migrate-elasticsearch-to-opensearch.adoc[leveloffset=+1]
-
 == Queries and aggregations
 
 include::queries-and-aggregations.adoc[]
@@ -99,6 +89,19 @@ include::clustering.adoc[]
 
 == Reference
 
+=== Architecture Overview
+
+include::architecture.adoc[]
+
+==== Data Structures
+include::data-structures.adoc[]
+
+==== Event Processing Architecture
+include::event-processing.adoc[]
+
+==== Security Architecture
+include::security.adoc[]
+
 include::useful-unomi-urls.adoc[]
 
 include::how-profile-tracking-works.adoc[]
@@ -107,6 +110,8 @@ include::context-request-flow.adoc[]
 
 include::datamodel.adoc[]
 
+include::property-types.adoc[]
+
 include::builtin-event-types.adoc[]
 
 include::builtin-condition-types.adoc[]
@@ -119,6 +124,9 @@ include::past-event-conditions.adoc[]
 
 include::web-tracker.adoc[]
 
+include::javascript-tracker-guide.adoc[]
+
+[[_integration_samples]]
 == Integration samples
 
 include::samples/samples.adoc[]
@@ -144,5 +152,3 @@ include::shell-commands.adoc[]
 include::writing-plugins.adoc[]
 
 include::patches.adoc[]
-
-include::migrate-es7-to-es9.adoc[]
diff --git a/manual/src/main/asciidoc/javascript-tracker-guide.adoc b/manual/src/main/asciidoc/javascript-tracker-guide.adoc
new file mode 100644
index 000000000..044945bd8
--- /dev/null
+++ b/manual/src/main/asciidoc/javascript-tracker-guide.adoc
@@ -0,0 +1,1260 @@
+//
+// 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.
+//
+=== Implementing a JavaScript Tracker
+
+This guide explains how to implement a basic JavaScript tracker for Apache Unomi from scratch. This will help you understand the underlying concepts and API interactions, whether you're building a custom tracker or integrating Apache Unomi into an existing application.
+
+[NOTE]
+====
+Apache Unomi provides an official web tracker (see <<_unomi_web_tracker_reference,Unomi Web Tracker reference>>) that handles many of these details automatically. This guide is useful if you need a custom implementation or want to understand how the tracker works internally.
+====
+
+==== Prerequisites
+
+Before implementing a tracker, you need:
+
+* An Apache Unomi instance running and accessible
+* A tenant created with a public API key (see <<_request_examples,Request examples>> for tenant creation)
+* Basic knowledge of JavaScript and HTTP requests
+* Understanding of how profile tracking works (see <<_how_profile_tracking_works,How profile tracking works>>)
+
+==== Basic Tracker Structure
+
+A basic JavaScript tracker needs to:
+
+1. **Manage session and profile identifiers** - Generate and store session IDs, handle profile ID cookies
+2. **Make context requests** - Call `/cxs/context.json` to retrieve profile/session data
+3. **Send events** - Send user interaction events to Apache Unomi
+4. **Handle personalization** - Request and apply personalized content
+5. **Manage cookies** - Read and write cookies for profile tracking
+
+Here's a minimal tracker structure:
+
+[source,javascript]
+----
+(function() {
+    'use strict';
+
+    // Configuration
+    const CONFIG = {
+        contextServerUrl: 'http://localhost:8181',
+        apiKey: 'YOUR_PUBLIC_API_KEY',
+        scope: 'mydigital',
+        sessionCookieName: 'unomi-session-id',
+        profileCookieName: 'context-profile-id'
+    };
+
+    // Tracker object
+    const tracker = {
+        // Session management
+        getSessionId: function() { /* ... */ },
+        setSessionId: function(sessionId) { /* ... */ },
+        
+        // Cookie utilities
+        getCookie: function(name) { /* ... */ },
+        setCookie: function(name, value, days) { /* ... */ },
+        
+        // Context requests
+        getContext: function(options, callback) { /* ... */ },
+        
+        // Event tracking
+        trackEvent: function(event, callback) { /* ... */ },
+        trackEvents: function(events, callback) { /* ... */ },
+        
+        // Personalization
+        personalize: function(personalizations, callback) { /* ... */ },
+        
+        // Initialization
+        init: function() { /* ... */ }
+    };
+
+    // Expose tracker globally
+    window.unomiTracker = tracker;
+})();
+----
+
+==== Cookie Management
+
+The tracker needs to read and write cookies to maintain the session ID and handle the profile ID cookie set by Apache Unomi.
+
+[source,javascript]
+----
+// Cookie utilities
+getCookie: function(name) {
+    const value = `; ${document.cookie}`;
+    const parts = value.split(`; ${name}=`);
+    if (parts.length === 2) {
+        return parts.pop().split(';').shift();
+    }
+    return null;
+},
+
+setCookie: function(name, value, days) {
+    const expires = new Date();
+    expires.setTime(expires.getTime() + (days * 24 * 60 * 60 * 1000));
+    document.cookie = `${name}=${value};expires=${expires.toUTCString()};path=/`;
+},
+
+deleteCookie: function(name) {
+    document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 UTC;path=/;`;
+}
+----
+
+==== Session Management
+
+The tracker needs to generate and maintain a session ID. If no session ID exists, generate a new one:
+
+[source,javascript]
+----
+// Generate a UUID v4
+// Uses crypto.randomUUID() if available (most secure, modern browsers)
+// Falls back to crypto.getRandomValues() (secure, widely supported)
+// Falls back to Math.random() only for very old browsers (less secure)
+generateUUID: function() {
+    // Use crypto.randomUUID() if available (Chrome 92+, Firefox 95+, Safari 15.4+, Node.js 19+)
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    
+    // Use crypto.getRandomValues() if available (widely supported, secure)
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+            const r = crypto.getRandomValues(new Uint8Array(1))[0] % 16;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+    
+    // Fallback to Math.random() for very old browsers (not cryptographically secure)
+    // Note: This is less secure and should only be used as a last resort
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+},
+
+// Get or create session ID
+getSessionId: function() {
+    let sessionId = this.getCookie(CONFIG.sessionCookieName);
+    if (!sessionId) {
+        sessionId = this.generateUUID();
+        this.setSessionId(sessionId);
+    }
+    return sessionId;
+},
+
+setSessionId: function(sessionId) {
+    this.setCookie(CONFIG.sessionCookieName, sessionId, 1); // 1 day expiration
+}
+----
+
+==== Making Context Requests
+
+The core of the tracker is making requests to `/cxs/context.json`. This endpoint:
+
+* Automatically creates or loads profiles and sessions
+* Processes events
+* Resolves personalization
+* Returns profile and session data
+
+[source,javascript]
+----
+// Make a context request
+getContext: function(options, callback) {
+    const sessionId = this.getSessionId();
+    const url = `${CONFIG.contextServerUrl}/cxs/context.json?sessionId=${encodeURIComponent(sessionId)}`;
+    
+    // Build request payload
+    const payload = {
+        source: {
+            itemId: options.sourceId || window.location.pathname,
+            itemType: options.sourceType || 'page',
+            scope: CONFIG.scope
+        }
+    };
+    
+    // Add optional parameters
+    if (options.requiredProfileProperties) {
+        payload.requiredProfileProperties = options.requiredProfileProperties;
+    }
+    if (options.requiredSessionProperties) {
+        payload.requiredSessionProperties = options.requiredSessionProperties;
+    }
+    if (options.requireSegments) {
+        payload.requireSegments = true;
+    }
+    if (options.requireScores) {
+        payload.requireScores = true;
+    }
+    if (options.events) {
+        payload.events = options.events;
+    }
+    if (options.filters) {
+        payload.filters = options.filters;
+    }
+    if (options.personalizations) {
+        payload.personalizations = options.personalizations;
+    }
+    
+    // Make the request
+    const xhr = new XMLHttpRequest();
+    xhr.open('POST', url, true);
+    xhr.setRequestHeader('Content-Type', 'application/json');
+    xhr.setRequestHeader('X-Unomi-Api-Key', CONFIG.apiKey);
+    xhr.withCredentials = true; // Important for cookies
+    
+    xhr.onreadystatechange = function() {
+        if (xhr.readyState === 4) {
+            if (xhr.status === 200) {
+                try {
+                    const response = JSON.parse(xhr.responseText);
+                    if (callback) {
+                        callback(null, response);
+                    }
+                } catch (e) {
+                    if (callback) {
+                        callback(new Error('Failed to parse response: ' + e.message), null);
+                    }
+                }
+            } else {
+                if (callback) {
+                    callback(new Error('Request failed with status: ' + xhr.status), null);
+                }
+            }
+        }
+    };
+    
+    xhr.send(JSON.stringify(payload));
+}
+----
+
+==== Retrieving Profile and Session Properties
+
+To retrieve profile and session properties, include them in the context request:
+
+[source,javascript]
+----
+// Get all profile and session properties
+tracker.getContext({
+    requireSegments: true,
+    requireScores: true,
+    requiredProfileProperties: ['*'], // '*' means all properties
+    requiredSessionProperties: ['*']
+}, function(error, response) {
+    if (error) {
+        console.error('Failed to get context:', error);
+        return;
+    }
+    
+    console.log('Profile ID:', response.profileId);
+    console.log('Session ID:', response.sessionId);
+    console.log('Profile Properties:', response.profileProperties);
+    console.log('Session Properties:', response.sessionProperties);
+    console.log('Profile Segments:', response.profileSegments);
+    console.log('Profile Scores:', response.profileScores);
+});
+----
+
+You can also request specific properties:
+
+[source,javascript]
+----
+// Get specific profile properties
+tracker.getContext({
+    requiredProfileProperties: ['firstName', 'lastName', 'email', 'pageViewCount']
+}, function(error, response) {
+    if (error) {
+        console.error('Failed to get context:', error);
+        return;
+    }
+    
+    const profile = response.profileProperties || {};
+    console.log('User:', profile.firstName, profile.lastName);
+    console.log('Email:', profile.email);
+    console.log('Page Views:', profile.pageViewCount);
+});
+----
+
+==== Sending Events
+
+Events are sent as part of the context request. You can send a single event or multiple events in one request:
+
+[source,javascript]
+----
+// Build an event object
+buildEvent: function(eventType, target, source) {
+    const event = {
+        eventType: eventType,
+        scope: CONFIG.scope
+    };
+    
+    // Set source if provided, otherwise use default based on event type
+    if (source) {
+        event.source = source;
+    } else if (eventType === 'view') {
+        // For view events, source should typically be a site
+        event.source = {
+            itemType: 'site',
+            scope: CONFIG.scope,
+            itemId: window.location.hostname || 'default-site'
+        };
+    } else {
+        // For other events, source defaults to the current page
+        event.source = {
+            itemType: 'page',
+            scope: CONFIG.scope,
+            itemId: window.location.pathname
+        };
+    }
+    
+    // Set target if provided
+    if (target) {
+        event.target = target;
+    }
+    
+    return event;
+},
+
+// Track a single event
+trackEvent: function(event, callback) {
+    this.getContext({
+        events: [event]
+    }, callback);
+},
+
+// Track multiple events (more efficient)
+trackEvents: function(events, callback) {
+    this.getContext({
+        events: events
+    }, callback);
+}
+----
+
+**Example: Tracking a page view**
+
+[source,javascript]
+----
+// Track a page view event
+const viewEvent = tracker.buildEvent('view', {
+    itemType: 'page',
+    scope: CONFIG.scope,
+    itemId: window.location.pathname,
+    properties: {
+        pageInfo: {
+            pageName: document.title,
+            destinationURL: window.location.href,
+            referringURL: document.referrer
+        }
+    }
+}, {
+    itemType: 'site',
+    scope: CONFIG.scope,
+    itemId: window.location.hostname || 'default-site'
+});
+
+tracker.trackEvent(viewEvent, function(error, response) {
+    if (error) {
+        console.error('Failed to track view event:', error);
+        return;
+    }
+    console.log('View event tracked. Processed events:', response.processedEvents);
+});
+----
+
+**Example: Tracking a click event**
+
+[source,javascript]
+----
+// Track a click on a button
+function trackButtonClick(buttonId, buttonText) {
+    const clickEvent = tracker.buildEvent('click', {
+        itemType: 'button',
+        scope: CONFIG.scope,
+        itemId: buttonId,
+        properties: {
+            text: buttonText
+        }
+    });
+    
+    tracker.trackEvent(clickEvent, function(error, response) {
+        if (error) {
+            console.error('Failed to track click:', error);
+            return;
+        }
+        console.log('Click event tracked');
+    });
+}
+
+// Use it
+document.getElementById('myButton').addEventListener('click', function() {
+    trackButtonClick('myButton', 'Click Me');
+});
+----
+
+**Example: Tracking a form submission**
+
+[source,javascript]
+----
+// Track a form submission
+function trackFormSubmission(formId, formData) {
+    const formEvent = {
+        eventType: 'form',
+        scope: CONFIG.scope,
+        source: {
+            itemType: 'page',
+            scope: CONFIG.scope,
+            itemId: window.location.pathname
+        },
+        target: {
+            itemType: 'form',
+            scope: CONFIG.scope,
+            itemId: formId,
+            properties: formData
+        }
+    };
+    
+    tracker.trackEvent(formEvent, function(error, response) {
+        if (error) {
+            console.error('Failed to track form:', error);
+            return;
+        }
+        console.log('Form event tracked');
+    });
+}
+
+// Use it
+document.getElementById('myForm').addEventListener('submit', function(e) {
+    e.preventDefault();
+    const formData = {
+        formName: this.id,
+        formFields: {}
+    };
+    
+    // Extract form field values
+    Array.from(this.elements).forEach(function(element) {
+        if (element.name) {
+            formData.formFields[element.name] = element.value;
+        }
+    });
+    
+    trackFormSubmission(this.id, formData);
+});
+----
+
+==== Using Filters
+
+Filters allow you to evaluate conditions against the profile and session to determine which content should be displayed. Filters return boolean results indicating whether conditions match.
+
+[source,javascript]
+----
+// Request filter evaluation
+tracker.getContext({
+    filters: [
+        {
+            id: 'premium-user-filter',
+            filters: [
+                {
+                    condition: {
+                        type: 'profileSegmentCondition',
+                        parameterValues: {
+                            segments: ['premium-users']
+                        }
+                    }
+                }
+            ]
+        },
+        {
+            id: 'new-visitor-filter',
+            filters: [
+                {
+                    condition: {
+                        type: 'profilePropertyCondition',
+                        parameterValues: {
+                            propertyName: 'properties.firstVisit',
+                            comparisonOperator: 'exists'
+                        }
+                    }
+                }
+            ]
+        }
+    ]
+}, function(error, response) {
+    if (error) {
+        console.error('Failed to evaluate filters:', error);
+        return;
+    }
+    
+    const results = response.filteringResults || {};
+    if (results['premium-user-filter']) {
+        console.log('User is a premium user');
+        // Show premium content
+    }
+    if (results['new-visitor-filter']) {
+        console.log('User is a new visitor');
+        // Show welcome message
+    }
+});
+----
+
+==== Using Personalization
+
+Personalization allows you to request content variants and have Apache Unomi select the most appropriate one based on the profile and session state.
+
+[source,javascript]
+----
+// Request personalization
+tracker.getContext({
+    personalizations: [
+        {
+            id: 'homepage-hero',
+            strategy: 'matching-first',
+            strategyOptions: {
+                fallback: 'default-hero'
+            },
+            contents: [
+                {
+                    id: 'premium-user-hero',
+                    filters: [
+                        {
+                            condition: {
+                                type: 'profileSegmentCondition',
+                                parameterValues: {
+                                    segments: ['premium-users']
+                                }
+                            }
+                        }
+                    ]
+                },
+                {
+                    id: 'new-visitor-hero',
+                    filters: [
+                        {
+                            condition: {
+                                type: 'profilePropertyCondition',
+                                parameterValues: {
+                                    propertyName: 'properties.firstVisit',
+                                    comparisonOperator: 'exists'
+                                }
+                            }
+                        }
+                    ]
+                },
+                {
+                    id: 'default-hero'
+                }
+            ]
+        }
+    ]
+}, function(error, response) {
+    if (error) {
+        console.error('Failed to get personalization:', error);
+        return;
+    }
+    
+    // Get selected content ID(s)
+    // Note: personalizations is deprecated but still available
+    // It returns a List<String>, so get the first element for single-selection strategies
+    const contentIds = response.personalizations['homepage-hero'];
+    const selectedContentId = contentIds && contentIds.length > 0 ? contentIds[0] : null;
+    
+    // Alternatively, use personalizationResults for more detailed information
+    const personalizationResult = response.personalizationResults['homepage-hero'];
+    if (personalizationResult && personalizationResult.contentIds && personalizationResult.contentIds.length > 0) {
+        const selectedId = personalizationResult.contentIds[0];
+        console.log('Selected content:', selectedId);
+        console.log('Strategy used:', personalizationResult.strategy);
+        applyPersonalizedContent('homepage-hero', selectedId);
+    } else if (selectedContentId) {
+        console.log('Selected content:', selectedContentId);
+        applyPersonalizedContent('homepage-hero', selectedContentId);
+    } else {
+        console.log('No content selected, using fallback');
+        applyPersonalizedContent('homepage-hero', 'default-hero');
+    }
+});
+
+function applyPersonalizedContent(personalizationId, contentId) {
+    // Your logic to apply the personalized content
+    const element = document.getElementById(personalizationId);
+    if (element) {
+        // Example: Update content based on selected ID
+        if (contentId === 'premium-user-hero') {
+            element.innerHTML = '<h1>Welcome, Premium Member!</h1>';
+        } else if (contentId === 'new-visitor-hero') {
+            element.innerHTML = '<h1>Welcome! Sign up today!</h1>';
+        } else {
+            element.innerHTML = '<h1>Welcome!</h1>';
+        }
+    }
+}
+----
+
+==== Complete Example: Page Load with Personalization
+
+Here's a complete example that loads context, tracks a page view, and applies personalization on page load:
+
+[source,javascript]
+----
+// Initialize tracker on page load
+tracker.init = function() {
+    const sessionId = this.getSessionId();
+    
+    // Build page view event
+    const viewEvent = this.buildEvent('view', {
+        itemType: 'page',
+        scope: CONFIG.scope,
+        itemId: window.location.pathname,
+        properties: {
+            pageInfo: {
+                pageName: document.title,
+                destinationURL: window.location.href,
+                referringURL: document.referrer
+            }
+        }
+    });
+    
+    // Request context with event and personalization
+    this.getContext({
+        events: [viewEvent],
+        requireSegments: true,
+        requiredProfileProperties: ['firstName', 'lastName', 'pageViewCount'],
+        personalizations: [
+            {
+                id: 'homepage-hero',
+                strategy: 'matching-first',
+                strategyOptions: {
+                    fallback: 'default-hero'
+                },
+                contents: [
+                    {
+                        id: 'premium-user-hero',
+                        filters: [
+                            {
+                                condition: {
+                                    type: 'profileSegmentCondition',
+                                    parameterValues: {
+                                        segments: ['premium-users']
+                                    }
+                                }
+                            }
+                        ]
+                    },
+                    {
+                        id: 'new-visitor-hero',
+                        filters: [
+                            {
+                                condition: {
+                                    type: 'profilePropertyCondition',
+                                    parameterValues: {
+                                        propertyName: 'properties.firstVisit',
+                                        comparisonOperator: 'exists'
+                                    }
+                                }
+                            }
+                        ]
+                    },
+                    {
+                        id: 'default-hero'
+                    }
+                ]
+            }
+        ]
+    }, function(error, response) {
+        if (error) {
+            console.error('Failed to initialize tracker:', error);
+            return;
+        }
+        
+        // Log profile information
+        console.log('Profile ID:', response.profileId);
+        console.log('Session ID:', response.sessionId);
+        console.log('Profile Segments:', response.profileSegments);
+        
+        // Apply personalization
+        // Get the first content ID from the list (for single-selection strategies like 'matching-first')
+        // Note: personalizations returns a List<String>, so get the first element
+        const contentIds = response.personalizations && response.personalizations['homepage-hero'];
+        const selectedContentId = contentIds && contentIds.length > 0 ? contentIds[0] : 'default-hero';
+        applyPersonalizedContent('homepage-hero', selectedContentId);
+        
+        // Update UI with profile data
+        if (response.profileProperties) {
+            const profile = response.profileProperties;
+            if (profile.firstName) {
+                updateWelcomeMessage(profile.firstName, profile.lastName);
+            }
+            if (profile.pageViewCount) {
+                updatePageViewCount(profile.pageViewCount);
+            }
+        }
+    });
+};
+
+function applyPersonalizedContent(personalizationId, contentId) {
+    const element = document.getElementById(personalizationId);
+    if (!element) return;
+    
+    const contentMap = {
+        'premium-user-hero': '<div class="hero premium"><h1>Welcome, Premium Member!</h1><p>Thank you for your loyalty.</p></div>',
+        'new-visitor-hero': '<div class="hero new-visitor"><h1>Welcome!</h1><p>Sign up today and get 10% off your first purchase.</p></div>',
+        'default-hero': '<div class="hero default"><h1>Welcome!</h1><p>Discover our amazing products.</p></div>'
+    };
+    
+    element.innerHTML = contentMap[contentId] || contentMap['default-hero'];
+}
+
+function updateWelcomeMessage(firstName, lastName) {
+    const element = document.getElementById('welcome-message');
+    if (element) {
+        element.textContent = `Welcome back, ${firstName} ${lastName}!`;
+    }
+}
+
+function updatePageViewCount(count) {
+    const element = document.getElementById('page-view-count');
+    if (element) {
+        element.textContent = `You've viewed ${count} pages`;
+    }
+}
+
+// Initialize when DOM is ready
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() {
+        tracker.init();
+    });
+} else {
+    tracker.init();
+}
+----
+
+==== Advanced Features
+
+===== Batch Event Tracking
+
+For better performance, batch multiple events into a single request:
+
+[source,javascript]
+----
+// Track multiple events in one request
+const events = [
+    tracker.buildEvent('view', { /* ... */ }),
+    tracker.buildEvent('click', { /* ... */ }),
+    tracker.buildEvent('form', { /* ... */ })
+];
+
+tracker.trackEvents(events, function(error, response) {
+    if (error) {
+        console.error('Failed to track events:', error);
+        return;
+    }
+    console.log('Tracked', response.processedEvents, 'events');
+});
+----
+
+===== Event Queue
+
+Implement an event queue to batch events and send them periodically or when a threshold is reached:
+
+[source,javascript]
+----
+// Event queue implementation
+const eventQueue = {
+    queue: [],
+    maxSize: 10,
+    flushInterval: 5000, // 5 seconds
+    
+    add: function(event) {
+        this.queue.push(event);
+        if (this.queue.length >= this.maxSize) {
+            this.flush();
+        }
+    },
+    
+    flush: function() {
+        if (this.queue.length === 0) return;
+        
+        const events = this.queue.slice();
+        this.queue = [];
+        
+        tracker.trackEvents(events, function(error, response) {
+            if (error) {
+                console.error('Failed to flush events:', error);
+                // Re-add events to queue on error
+                eventQueue.queue = events.concat(eventQueue.queue);
+            } else {
+                console.log('Flushed', response.processedEvents, 'events');
+            }
+        });
+    },
+    
+    start: function() {
+        setInterval(function() {
+            eventQueue.flush();
+        }, this.flushInterval);
+    }
+};
+
+// Start automatic flushing
+eventQueue.start();
+
+// Add events to queue
+eventQueue.add(tracker.buildEvent('click', { /* ... */ }));
+----
+
+===== Error Handling and Retry Logic
+
+Implement robust error handling with retry logic:
+
+[source,javascript]
+----
+// Enhanced context request with retry logic
+getContextWithRetry: function(options, callback, maxRetries) {
+    maxRetries = maxRetries || 3;
+    let retries = 0;
+    
+    const attempt = () => {
+        this.getContext(options, function(error, response) {
+            if (error && retries < maxRetries) {
+                retries++;
+                console.warn('Request failed, retrying...', retries);
+                setTimeout(attempt, 1000 * retries); // Exponential backoff
+            } else {
+                callback(error, response);
+            }
+        });
+    };
+    
+    attempt();
+}
+----
+
+===== Profile ID Synchronization
+
+The profile ID is set by Apache Unomi in a cookie. Make sure to read it from the response:
+
+[source,javascript]
+----
+// Enhanced context request that handles profile ID cookie
+getContext: function(options, callback) {
+    // ... existing code ...
+    
+    xhr.onreadystatechange = function() {
+        if (xhr.readyState === 4) {
+            if (xhr.status === 200) {
+                try {
+                    const response = JSON.parse(xhr.responseText);
+                    
+                    // Profile ID cookie is automatically set by Apache Unomi
+                    // but we can verify it matches the response
+                    const cookieProfileId = tracker.getCookie(CONFIG.profileCookieName);
+                    if (response.profileId && cookieProfileId !== response.profileId) {
+                        console.warn('Profile ID mismatch:', {
+                            cookie: cookieProfileId,
+                            response: response.profileId
+                        });
+                    }
+                    
+                    if (callback) {
+                        callback(null, response);
+                    }
+                } catch (e) {
+                    if (callback) {
+                        callback(new Error('Failed to parse response: ' + e.message), null);
+                    }
+                }
+            } else {
+                if (callback) {
+                    callback(new Error('Request failed with status: ' + xhr.status), null);
+                }
+            }
+        }
+    };
+    
+    // ... rest of existing code ...
+}
+----
+
+===== Consent Management
+
+Handle user consent for tracking:
+
+[source,javascript]
+----
+// Check if user has consented to tracking
+hasConsent: function(consentType) {
+    // Check localStorage or cookie for consent
+    const consent = localStorage.getItem('unomi-consent-' + consentType);
+    return consent === 'true';
+},
+
+// Request context only if consent is given
+getContextWithConsent: function(options, callback) {
+    if (!this.hasConsent('tracking')) {
+        console.warn('User has not consented to tracking');
+        if (callback) {
+            callback(new Error('Consent required'), null);
+        }
+        return;
+    }
+    
+    this.getContext(options, callback);
+}
+----
+
+===== Cross-Domain Tracking
+
+For cross-domain tracking, ensure cookies are set with the correct domain:
+
+[source,javascript]
+----
+// Enhanced cookie setting with domain support
+setCookie: function(name, value, days, domain) {
+    const expires = new Date();
+    expires.setTime(expires.getTime() + (days * 24 * 60 * 60 * 1000));
+    
+    let cookie = `${name}=${value};expires=${expires.toUTCString()};path=/`;
+    if (domain) {
+        cookie += `;domain=${domain}`;
+    }
+    
+    document.cookie = cookie;
+}
+----
+
+===== Performance Optimization
+
+Optimize performance by:
+
+* **Debouncing events**: Don't send every single interaction immediately
+* **Batching requests**: Combine multiple operations into one request
+* **Caching context**: Cache profile data and only refresh when needed
+
+[source,javascript]
+----
+// Debounce function
+debounce: function(func, wait) {
+    let timeout;
+    return function executedFunction(...args) {
+        const later = () => {
+            clearTimeout(timeout);
+            func(...args);
+        };
+        clearTimeout(timeout);
+        timeout = setTimeout(later, wait);
+    };
+},
+
+// Debounced event tracking
+trackEventDebounced: this.debounce(function(event) {
+    tracker.trackEvent(event, function(error, response) {
+        if (error) {
+            console.error('Failed to track event:', error);
+        }
+    });
+}, 1000), // Wait 1 second before sending
+
+// Context caching
+contextCache: {
+    data: null,
+    timestamp: null,
+    ttl: 60000, // 1 minute
+    
+    get: function() {
+        if (this.data && this.timestamp && (Date.now() - this.timestamp) < this.ttl) {
+            return this.data;
+        }
+        return null;
+    },
+    
+    set: function(data) {
+        this.data = data;
+        this.timestamp = Date.now();
+    },
+    
+    clear: function() {
+        this.data = null;
+        this.timestamp = null;
+    }
+}
+----
+
+==== Complete Tracker Implementation
+
+Here's a complete, production-ready tracker implementation combining all the concepts:
+
+[source,javascript]
+----
+(function() {
+    'use strict';
+
+    const CONFIG = {
+        contextServerUrl: 'http://localhost:8181',
+        apiKey: 'YOUR_PUBLIC_API_KEY',
+        scope: 'mydigital',
+        sessionCookieName: 'unomi-session-id',
+        profileCookieName: 'context-profile-id',
+        eventQueueSize: 10,
+        eventQueueInterval: 5000
+    };
+
+    const tracker = {
+        // Cookie management
+        getCookie: function(name) {
+            const value = `; ${document.cookie}`;
+            const parts = value.split(`; ${name}=`);
+            if (parts.length === 2) {
+                return parts.pop().split(';').shift();
+            }
+            return null;
+        },
+        
+        setCookie: function(name, value, days, domain) {
+            const expires = new Date();
+            expires.setTime(expires.getTime() + (days * 24 * 60 * 60 * 1000));
+            let cookie = `${name}=${value};expires=${expires.toUTCString()};path=/`;
+            if (domain) {
+                cookie += `;domain=${domain}`;
+            }
+            document.cookie = cookie;
+        },
+        
+        // UUID generation
+        // Uses crypto.randomUUID() if available (most secure, modern browsers)
+        // Falls back to crypto.getRandomValues() (secure, widely supported)
+        // Falls back to Math.random() only for very old browsers (less secure)
+        generateUUID: function() {
+            // Use crypto.randomUUID() if available (Chrome 92+, Firefox 95+, Safari 15.4+, Node.js 19+)
+            if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+                return crypto.randomUUID();
+            }
+            
+            // Use crypto.getRandomValues() if available (widely supported, secure)
+            if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+                return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+                    const r = crypto.getRandomValues(new Uint8Array(1))[0] % 16;
+                    const v = c === 'x' ? r : (r & 0x3 | 0x8);
+                    return v.toString(16);
+                });
+            }
+            
+            // Fallback to Math.random() for very old browsers (not cryptographically secure)
+            // Note: This is less secure and should only be used as a last resort
+            return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+                const r = Math.random() * 16 | 0;
+                const v = c === 'x' ? r : (r & 0x3 | 0x8);
+                return v.toString(16);
+            });
+        },
+        
+        // Session management
+        getSessionId: function() {
+            let sessionId = this.getCookie(CONFIG.sessionCookieName);
+            if (!sessionId) {
+                sessionId = this.generateUUID();
+                this.setSessionId(sessionId);
+            }
+            return sessionId;
+        },
+        
+        setSessionId: function(sessionId) {
+            this.setCookie(CONFIG.sessionCookieName, sessionId, 1);
+        },
+        
+        // Event building
+        buildEvent: function(eventType, target, source) {
+            return {
+                eventType: eventType,
+                scope: CONFIG.scope,
+                source: source || {
+                    itemType: 'page',
+                    scope: CONFIG.scope,
+                    itemId: window.location.pathname
+                },
+                target: target
+            };
+        },
+        
+        // Context request
+        getContext: function(options, callback) {
+            const sessionId = this.getSessionId();
+            const url = `${CONFIG.contextServerUrl}/cxs/context.json?sessionId=${encodeURIComponent(sessionId)}`;
+            
+            const payload = {
+                source: {
+                    itemId: options.sourceId || window.location.pathname,
+                    itemType: options.sourceType || 'page',
+                    scope: CONFIG.scope
+                }
+            };
+            
+            if (options.requiredProfileProperties) {
+                payload.requiredProfileProperties = options.requiredProfileProperties;
+            }
+            if (options.requiredSessionProperties) {
+                payload.requiredSessionProperties = options.requiredSessionProperties;
+            }
+            if (options.requireSegments) {
+                payload.requireSegments = true;
+            }
+            if (options.requireScores) {
+                payload.requireScores = true;
+            }
+            if (options.events) {
+                payload.events = options.events;
+            }
+            if (options.filters) {
+                payload.filters = options.filters;
+            }
+            if (options.personalizations) {
+                payload.personalizations = options.personalizations;
+            }
+            
+            const xhr = new XMLHttpRequest();
+            xhr.open('POST', url, true);
+            xhr.setRequestHeader('Content-Type', 'application/json');
+            xhr.setRequestHeader('X-Unomi-Api-Key', CONFIG.apiKey);
+            xhr.withCredentials = true;
+            
+            xhr.onreadystatechange = function() {
+                if (xhr.readyState === 4) {
+                    if (xhr.status === 200) {
+                        try {
+                            const response = JSON.parse(xhr.responseText);
+                            if (callback) {
+                                callback(null, response);
+                            }
+                        } catch (e) {
+                            if (callback) {
+                                callback(new Error('Failed to parse response: ' + e.message), null);
+                            }
+                        }
+                    } else {
+                        if (callback) {
+                            callback(new Error('Request failed with status: ' + xhr.status), null);
+                        }
+                    }
+                }
+            };
+            
+            xhr.send(JSON.stringify(payload));
+        },
+        
+        // Event tracking
+        trackEvent: function(event, callback) {
+            this.getContext({
+                events: [event]
+            }, callback);
+        },
+        
+        trackEvents: function(events, callback) {
+            this.getContext({
+                events: events
+            }, callback);
+        },
+        
+        // Initialization
+        init: function(config) {
+            // Merge custom config
+            if (config) {
+                Object.assign(CONFIG, config);
+            }
+            
+            // Initialize session
+            this.getSessionId();
+            
+            // Track page view
+            const viewEvent = this.buildEvent('view', {
+                itemType: 'page',
+                scope: CONFIG.scope,
+                itemId: window.location.pathname,
+                properties: {
+                    pageInfo: {
+                        pageName: document.title,
+                        destinationURL: window.location.href,
+                        referringURL: document.referrer
+                    }
+                }
+            });
+            
+            this.trackEvent(viewEvent, function(error, response) {
+                if (error) {
+                    console.error('Failed to track page view:', error);
+                } else {
+                    console.log('Page view tracked');
+                }
+            });
+        }
+    };
+
+    // Expose tracker
+    window.unomiTracker = tracker;
+    
+    // Auto-initialize if DOM is ready
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', function() {
+            tracker.init();
+        });
+    } else {
+        tracker.init();
+    }
+})();
+----
+
+==== Best Practices
+
+1. **Always use HTTPS in production** - Update `contextServerUrl` to use HTTPS
+2. **Handle errors gracefully** - Don't break the user experience if tracking fails
+3. **Respect user privacy** - Implement consent management
+4. **Optimize performance** - Batch events, cache context, debounce rapid interactions
+5. **Test thoroughly** - Test with different browsers, network conditions, and privacy settings
+6. **Monitor and log** - Log errors and track success rates
+7. **Keep session IDs secure** - Use cryptographically secure UUID generation (see UUID generation section below)
+8. **Handle cookie restrictions** - Some browsers block third-party cookies
+
+==== UUID Generation Security
+
+[IMPORTANT]
+====
+**Security Considerations for UUID Generation**
+
+The tracker uses UUIDs for session IDs, which should be unpredictable to prevent session hijacking. The implementation in this guide uses a secure fallback chain:
+
+1. **`crypto.randomUUID()`** (Preferred): Available in modern browsers (Chrome 92+, Firefox 95+, Safari 15.4+, Edge 92+). This is the most secure option and generates RFC 4122-compliant UUIDs using cryptographically secure random number generation.
+
+2. **`crypto.getRandomValues()`** (Fallback): Available in all modern browsers (IE 11+, Chrome 11+, Firefox 21+, Safari 5.1+). Uses the Web Crypto API to generate cryptographically secure random values. This is secure and widely compatible.
+
+3. **`Math.random()`** (Last Resort): Only used for very old browsers that don't support the Web Crypto API. This is **not cryptographically secure** and can be predictable, making it vulnerable to session hijacking attacks.
+
+**Recommendations:**
+* For production applications, ensure your minimum browser support includes browsers with `crypto.getRandomValues()` support (essentially all browsers from 2013+)
+* If you need to support very old browsers (IE 10 and below), consider using a polyfill or warning users about security limitations
+* Never use `Math.random()` alone for security-sensitive identifiers like session IDs or authentication tokens
+* The profile ID is always generated server-side by Apache Unomi using secure UUID generation, so client-side UUID generation is only needed for session IDs
+
+**Browser Compatibility:**
+* `crypto.randomUUID()`: Chrome 92+, Firefox 95+, Safari 15.4+, Edge 92+ (2021+)
+* `crypto.getRandomValues()`: All modern browsers (2013+)
+* `Math.random()`: All browsers (but not secure)
+
+For maximum security and compatibility, the implementation automatically uses the best available method.
+====
+
+==== Next Steps
+
+* Learn about <<_how_profile_tracking_works,How profile tracking works>> to understand the full flow
+* Review the <<_unomi_web_tracker_reference,official Unomi Web Tracker>> for a production-ready implementation
+* Explore <<_request_examples,Request examples>> for more API usage patterns
+* Check <<_builtin_event_types,Built-in event types>> for available event types
+* Review <<_builtin_condition_types,Built-in condition types>> for filter conditions
diff --git a/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc b/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc
index 17fa7916c..204da1dff 100644
--- a/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc
+++ b/manual/src/main/asciidoc/jsonSchema/extend-an-existing-schema.adoc
@@ -12,6 +12,7 @@
 // limitations under the License.
 //
 
+[[_extend_an_existing_schema]]
 === Extend an existing schema
 
 ==== When a extension is needed?
diff --git a/manual/src/main/asciidoc/jsonSchema/introduction.adoc b/manual/src/main/asciidoc/jsonSchema/introduction.adoc
index e77d5ed4d..046d14591 100644
--- a/manual/src/main/asciidoc/jsonSchema/introduction.adoc
+++ b/manual/src/main/asciidoc/jsonSchema/introduction.adoc
@@ -271,7 +271,7 @@ Each schema where the *target* value is set to *events*, will be used to validat
 The others are simply used as part of JSON schema or can be used in additional JSON schemas.
 
 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.
+in the <<_create_update_json_schema,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 require a restart of the platform to reflect changes.
diff --git a/manual/src/main/asciidoc/jsonSchema/json-schema-develop.adoc b/manual/src/main/asciidoc/jsonSchema/json-schema-develop.adoc
index 45ec0d50a..34e4b18cf 100644
--- a/manual/src/main/asciidoc/jsonSchema/json-schema-develop.adoc
+++ b/manual/src/main/asciidoc/jsonSchema/json-schema-develop.adoc
@@ -16,7 +16,7 @@
 
 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 
+This section of the documentation details 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
diff --git a/manual/src/main/asciidoc/migrations/migrate-1.4-to-1.5.adoc b/manual/src/main/asciidoc/migrations/migrate-1.4-to-1.5.adoc
index 6177853d0..c4dbf7064 100644
--- a/manual/src/main/asciidoc/migrations/migrate-1.4-to-1.5.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-1.4-to-1.5.adoc
@@ -12,9 +12,9 @@
 // limitations under the License.
 //
 
-=== Migration from Apache Unomi 1.4 to 1.5
+==== Migration from Apache Unomi 1.4 to 1.5
 
-==== Data model and ElasticSearch 7
+===== Data model and ElasticSearch 7
 
 Since Apache Unomi version 1.5.0 we decided to upgrade the supported ElasticSearch version to the 7.4.2.
 
@@ -24,7 +24,7 @@ Previously every items was stored inside the same ElasticSearch index but this i
 
 Since Apache Unomi version 1.5.0 every type of items (see section: link:#_items[Items]) is now stored in a dedicated separated index.
 
-==== API changes
+===== API changes
 
 To be able to handle the multiple indices the Persistence API implementation
 (https://github.com/apache/unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/persistence-elasticsearch/core/src/main/java/org/apache/unomi/persistence/elasticsearch/ElasticSearchPersistenceServiceImpl.java[ElasticSearchPersistenceServiceImpl])
@@ -50,7 +50,7 @@ Because of this changes the geonames DB index name is now respecting the index n
 Previously named: `geonames` is now using the index name `context-geonameentry`
 (see: link:#_installing_geonames_database[Documentation about geonames extension]).
 
-==== Migration steps
+===== Migration steps
 
 In order to migrate the data from ElasticSearch 5 to 7, Unomi provides a migration tool that is directly integrated.
 
diff --git a/manual/src/main/asciidoc/migrations/migrate-1.6-to-2.0.adoc b/manual/src/main/asciidoc/migrations/migrate-1.6-to-2.0.adoc
index d813afee0..fff03cefe 100644
--- a/manual/src/main/asciidoc/migrations/migrate-1.6-to-2.0.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-1.6-to-2.0.adoc
@@ -29,7 +29,7 @@ Doing so will display any errors when processing events (such as JSON Schema val
 
 ==== Data Model changes
 
-There has been changes to Unomi Data model, please make sure to review those in the <<_whats_new_in_apache_unomi_2_0,What's new in Unomi 2>> section of the user manual.
+There has been changes to Unomi Data model, please make sure to review those in the <<_whats_new,What's new>> section of the user manual.
 
 ==== Create JSON schemas
 
@@ -52,7 +52,7 @@ Once the debug logs are active, you will see detailed error messages if your eve
 
 Note that it is currently not possible to modify or surcharge an existing system-deployed JSON schema via the REST API. It is however possible to deploy new schemas and manage them through the REST API on the `/cxs/jsonSchema` endpoint.
 If you are currently using custom properties on an Apache Unomi-provided event type,
-you will need to either change to use a new custom eventType and create the corresponding schema or to create a Unomi schema extension. You can find more details in the <<JSON schemas,JSON Schema>> section of this documentation.
+you will need to either change to use a new custom eventType and create the corresponding schema or to create a Unomi schema extension. You can find more details in the <<_json_schemas,JSON Schema>> section of this documentation.
 
 You can use, as a source of inspiration for creating new schemas, Apache Unomi 2.0 schema located at:
  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].
diff --git a/manual/src/main/asciidoc/migrations/migrate-2.x-to-3.0.adoc b/manual/src/main/asciidoc/migrations/migrate-2.x-to-3.0.adoc
index 422f3e8fe..8b58df24e 100644
--- a/manual/src/main/asciidoc/migrations/migrate-2.x-to-3.0.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-2.x-to-3.0.adoc
@@ -261,11 +261,11 @@ When using Docker, you can specify the search engine backend using the distribut
 - **For OpenSearch**: `UNOMI_DISTRIBUTION=unomi-distribution-opensearch`
 - **For custom configurations**: `UNOMI_DISTRIBUTION=your-custom-distribution-name`
 
-==== Migrating from Elasticsearch to OpenSearch
+==== Elasticsearch to OpenSearch Migration
 
 Apache Unomi 3.1 introduces official support for OpenSearch as an alternative to Elasticsearch. If you want to migrate from Elasticsearch to OpenSearch, you can use the dedicated migration guide located in the 3.0 → 3.1 migration section.
 
-For detailed instructions on migrating your data from Elasticsearch to OpenSearch, please refer to the <<Migrating from Elasticsearch to OpenSearch,Elasticsearch to OpenSearch migration guide>>.
+For detailed instructions on migrating your data from Elasticsearch to OpenSearch, please refer to the <<_migrating_from_elasticsearch_to_opensearch,Elasticsearch to OpenSearch migration guide>>.
 
 ==== Migration Checklist
 
@@ -293,4 +293,4 @@ Before upgrading to Apache Unomi 3.0, complete the following checklist:
 
 ==== Other Breaking Changes
 
-For information about other breaking changes in Apache Unomi 3.0, please refer to the <<What's new in Apache Unomi 3.0,What's new>> section of the documentation.
+For information about other breaking changes in Apache Unomi 3.0, please refer to the <<_whats_new,What's new>> section of the documentation.
diff --git a/manual/src/main/asciidoc/migrations/migrate-elasticsearch-to-opensearch.adoc b/manual/src/main/asciidoc/migrations/migrate-elasticsearch-to-opensearch.adoc
index 83dbe1391..06316e129 100644
--- a/manual/src/main/asciidoc/migrations/migrate-elasticsearch-to-opensearch.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-elasticsearch-to-opensearch.adoc
@@ -12,7 +12,8 @@
 // limitations under the License.
 //
 
-== Migrating from Elasticsearch to OpenSearch
+[[_migrating_from_elasticsearch_to_opensearch]]
+==== Migrating from Elasticsearch to OpenSearch
 :toc: macro
 :toclevels: 4
 :toc-title: Table of contents
@@ -20,11 +21,11 @@
 
 toc::[]
 
-== Overview
+===== Overview
 
 This guide describes how to migrate your Apache Unomi data from Elasticsearch to OpenSearch. The migration process involves using the OpenSearch Replication Tool, which is designed to handle large-scale migrations efficiently while maintaining data consistency.
 
-== Prerequisites
+===== Prerequisites
 
 Before starting the migration, ensure you have:
 
@@ -34,13 +35,13 @@ Before starting the migration, ensure you have:
 * Java 11 or later installed
 * Network connectivity between source and target clusters
 
-== Migration Options
+===== Migration Options
 
-=== Option 1: OpenSearch Replication Tool (Recommended)
+====== Option 1: OpenSearch Replication Tool (Recommended)
 
 The OpenSearch Replication Tool is the recommended approach for production environments, especially for large datasets.
 
-==== Installation
+====== Installation
 
 [source,bash]
 ----
@@ -49,7 +50,7 @@ cd opensearch-migrations/replication-tool
 ./gradlew build
 ----
 
-==== Configuration
+====== Configuration
 
 Create a configuration file `config.yml`:
 
@@ -72,7 +73,7 @@ indices:
   - name: "session-*"         # Unomi session indices
 ----
 
-==== Running the Migration
+====== Running the Migration
 
 [source,bash]
 ----
@@ -81,11 +82,11 @@ indices:
 
 The tool provides progress updates and ensures data consistency during the migration.
 
-=== Option 2: Logstash Pipeline
+====== Option 2: Logstash Pipeline
 
 For smaller deployments or when more control over the migration process is needed, you can use Logstash.
 
-==== Logstash Configuration
+====== Logstash Configuration
 
 Create a file named `logstash-migration.conf`:
 
@@ -114,14 +115,14 @@ output {
 }
 ----
 
-==== Running Logstash Migration
+====== Running Logstash Migration
 
 [source,bash]
 ----
 logstash -f logstash-migration.conf
 ----
 
-== Post-Migration Steps
+===== Post-Migration Steps
 
 1. Verify Data Integrity
 +
@@ -158,9 +159,9 @@ org.apache.unomi.opensearch.password=admin
 ./bin/start
 ----
 
-== Troubleshooting
+===== Troubleshooting
 
-=== Common Issues
+====== Common Issues
 
 1. Connection Timeouts
 * Increase the timeout settings in your configuration
@@ -174,7 +175,7 @@ org.apache.unomi.opensearch.password=admin
 * Verify index patterns in configuration
 * Check source cluster health
 
-=== Monitoring Progress
+====== Monitoring Progress
 
 The OpenSearch Replication Tool provides progress information during migration:
 
@@ -183,7 +184,7 @@ The OpenSearch Replication Tool provides progress information during migration:
 * Current transfer rate
 * Estimated completion time
 
-== Best Practices
+===== Best Practices
 
 1. *Testing*
 * Always test the migration process in a non-production environment first
@@ -203,7 +204,7 @@ The OpenSearch Replication Tool provides progress information during migration:
 * Verify index mappings and settings
 * Test Unomi functionality with migrated data
 
-== Support
+===== Support
 
 For additional support:
 
diff --git a/manual/src/main/asciidoc/migrate-es7-to-es9.adoc b/manual/src/main/asciidoc/migrations/migrate-es7-to-es9.adoc
similarity index 93%
rename from manual/src/main/asciidoc/migrate-es7-to-es9.adoc
rename to manual/src/main/asciidoc/migrations/migrate-es7-to-es9.adoc
index d7a9c40ef..4afcdf17e 100644
--- a/manual/src/main/asciidoc/migrate-es7-to-es9.adoc
+++ b/manual/src/main/asciidoc/migrations/migrate-es7-to-es9.adoc
@@ -11,7 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
-=== Migrate from Elasticsearch 7 to Elasticsearch 9
+[[_migrate_from_elasticsearch_7_to_elasticsearch_9]]
+==== Migrate from Elasticsearch 7 to Elasticsearch 9
 
 You can use the *remote reindex* API to upgrade directly from Elasticsearch 7 to Elasticsearch 9. This approach runs both clusters in parallel and uses Elasticsearch's remote reindex feature.
 
@@ -25,7 +26,7 @@ The script migration_es7-es9.sh at the root of the project and handles:
 * Data reindexing from ES7 to ES9
 * Validation and comparison reporting
 
-==== Prerequisites
+===== Prerequisites
 
 * `bash` shell
 * `jq` command-line JSON processor
@@ -47,7 +48,7 @@ apt-get install jq
 yum install jq
 ----
 
-==== Elasticsearch 9 Remote Reindex Configuration
+===== Elasticsearch 9 Remote Reindex Configuration
 
 Before running the script, you must configure the remote reindex whitelist on your ES9 cluster. Add this to your `elasticsearch.yml` configuration file:
 
@@ -56,7 +57,7 @@ Before running the script, you must configure the remote reindex whitelist on yo
 reindex.remote.whitelist: "your-es7-host:9200"
 ----
 
-==== Script Configuration
+===== Script Configuration
 
 The script uses environment variables for configuration. Export variables before running the script:
 
@@ -75,7 +76,7 @@ export INDEX_PREFIX="context-"
 export BATCH_SIZE="1000"
 ----
 
-==== Configuration Variables
+===== Configuration Variables
 
 [cols="1,3,1", options="header"]
 |===
@@ -92,7 +93,7 @@ export BATCH_SIZE="1000"
 | BATCH_SIZE | Reindex batch size | 1000
 |===
 
-== Execution
+==== Execution
 
 Make the script executable and run it:
 
@@ -102,7 +103,7 @@ chmod +x migration_es7-es9.sh
 ./migration_es7-es9.sh
 ----
 
-==== What the Script Does
+===== What the Script Does
 
 * Discovers indices matching the configured patterns on ES7
 * Collects source statistics (document count, size) for each index
@@ -113,7 +114,7 @@ chmod +x migration_es7-es9.sh
 * Collects destination statistics after migration
 * Displays a comparison report showing document counts and any mismatches
 
-==== Output
+===== Output
 
 The script provides detailed logging with timestamps and a final comparison report:
 
diff --git a/manual/src/main/asciidoc/migrations/migrations.adoc b/manual/src/main/asciidoc/migrations/migrations.adoc
index 406176a93..7966c0f24 100644
--- a/manual/src/main/asciidoc/migrations/migrations.adoc
+++ b/manual/src/main/asciidoc/migrations/migrations.adoc
@@ -28,6 +28,8 @@ include::migrate-elasticsearch-to-opensearch.adoc[]
 
 include::migrate-2.x-to-3.0.adoc[]
 
+include::migrate-es7-to-es9.adoc[]
+
 === From version 1.6 to 2.0
 
 include::migrate-1.6-to-2.0.adoc[]
diff --git a/manual/src/main/asciidoc/multitenancy.adoc b/manual/src/main/asciidoc/multitenancy.adoc
index 4d8a75d32..2d98b1157 100644
--- a/manual/src/main/asciidoc/multitenancy.adoc
+++ b/manual/src/main/asciidoc/multitenancy.adoc
@@ -45,11 +45,13 @@ X-Unomi-Api-Key: <PUBLIC_KEY>
 === Private API Key
 Used for administrative operations and sensitive endpoints. Requires Basic Authentication using tenant ID and private key.
 
-[source,http]
+[source,bash]
 ----
-Authorization: Basic <BASE64(TENANT_ID:PRIVATE_KEY)>
+--user "TENANT_ID:PRIVATE_KEY"
 ----
 
+NOTE: curl automatically handles Base64 encoding when using the `--user` option, so you don't need to manually encode the credentials.
+
 == Getting Started
 
 === Creating Your First Tenant
@@ -59,16 +61,18 @@ To create a new tenant, use the Tenant API endpoint:
 [source,bash]
 ----
 curl -X POST http://localhost:8181/cxs/tenants \
+  --user karaf:karaf \
   -H "Content-Type: application/json" \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>" \
   -d '{
-    "itemId": "my-tenant",
-    "name": "My Organization",
-    "description": "My organization description"
+    "requestedId": "my-tenant",
+    "properties": {
+      "name": "My Organization",
+      "description": "My organization description"
+    }
   }'
 ----
 
-The response includes the tenant's API keys:
+The response includes the tenant with automatically generated API keys:
 
 [source,json]
 ----
@@ -76,11 +80,23 @@ The response includes the tenant's API keys:
   "itemId": "my-tenant",
   "name": "My Organization",
   "description": "My organization description",
-  "publicKey": "abc123...",
-  "privateKey": "xyz789..."
+  "apiKeys": [
+    {
+      "type": "PUBLIC",
+      "key": "abc123...",
+      "created": "2024-01-01T00:00:00Z"
+    },
+    {
+      "type": "PRIVATE",
+      "key": "xyz789...",
+      "created": "2024-01-01T00:00:00Z"
+    }
+  ]
 }
 ----
 
+NOTE: Both public and private API keys are automatically generated when creating a tenant. Extract the `key` value from the appropriate API key object in the `apiKeys` array.
+
 === Making Your First API Call
 
 ==== Public Endpoint Example (Context Request)
@@ -104,8 +120,8 @@ curl http://localhost:8181/cxs/context.json \
 
 [source,bash]
 ----
-curl http://localhost:8181/cxs/profiles \
-  -H "Authorization: Basic <BASE64(TENANT_ID:PRIVATE_KEY)>" \
+curl -X GET http://localhost:8181/cxs/profiles \
+  --user "TENANT_ID:PRIVATE_KEY" \
   -H "Content-Type: application/json"
 ----
 
@@ -344,8 +360,9 @@ securityService.executeAsSystemSubject(() -> {
 
 [source,bash]
 ----
-curl http://localhost:8181/cxs/tenants \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>"
+curl -X GET http://localhost:8181/cxs/tenants \
+  --user karaf:karaf \
+  -H "Content-Type: application/json"
 ----
 
 === Updating a Tenant
@@ -353,7 +370,7 @@ curl http://localhost:8181/cxs/tenants \
 [source,bash]
 ----
 curl -X PUT http://localhost:8181/cxs/tenants/my-tenant \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>" \
+  --user karaf:karaf \
   -H "Content-Type: application/json" \
   -d '{
     "displayName": "Updated Organization Name",
@@ -365,16 +382,24 @@ curl -X PUT http://localhost:8181/cxs/tenants/my-tenant \
 
 [source,bash]
 ----
-curl -X POST http://localhost:8181/cxs/tenants/my-tenant/keys \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>"
+curl -X POST http://localhost:8181/cxs/tenants/my-tenant/apikeys \
+  --user karaf:karaf \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "PUBLIC",
+    "validityDays": 30
+  }'
 ----
 
+NOTE: You can specify `type` as `PUBLIC` or `PRIVATE`, and optionally set `validityDays` for key expiration. If omitted, both keys will be regenerated.
+
 === Deleting a Tenant
 
 [source,bash]
 ----
 curl -X DELETE http://localhost:8181/cxs/tenants/my-tenant \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>"
+  --user karaf:karaf \
+  -H "Content-Type: application/json"
 ----
 
 == GraphQL Support
@@ -383,8 +408,8 @@ GraphQL endpoints support both public and private authentication methods:
 
 [source,bash]
 ----
-curl http://localhost:8181/graphql \
-  -H "Authorization: Basic <BASE64(TENANT_ID:PRIVATE_KEY)>" \
+curl -X POST http://localhost:8181/graphql \
+  --user "TENANT_ID:PRIVATE_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "query": "{ profiles { edges { node { id } } } }"
@@ -402,7 +427,7 @@ When a tenant accesses the GraphQL API:
 3. The schema only includes property types defined for that tenant
 4. Changes to a tenant's property types are automatically reflected in their schema
 
-For complete details on the GraphQL multi-tenancy implementation, refer to the <<GraphQL API>> section of the documentation.
+For complete details on the GraphQL multi-tenancy implementation, refer to the <<_graphql_api,GraphQL API>> section of the documentation.
 
 == Monitoring and Management
 
@@ -412,8 +437,9 @@ Track tenant API usage:
 
 [source,bash]
 ----
-curl http://localhost:8181/cxs/tenants/my-tenant/apiCalls \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>"
+curl -X GET http://localhost:8181/cxs/tenants/my-tenant/apiCalls \
+  --user karaf:karaf \
+  -H "Content-Type: application/json"
 ----
 
 === Data Migration
@@ -423,7 +449,8 @@ Migrate data between tenants:
 [source,bash]
 ----
 curl -X POST http://localhost:8181/cxs/tenants/source-tenant/migrate/target-tenant \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>"
+  --user karaf:karaf \
+  -H "Content-Type: application/json"
 ----
 
 == Best Practices
@@ -483,12 +510,20 @@ To migrate existing data to use multi-tenancy:
 ----
 # Step 1: Create new tenant
 curl -X POST http://localhost:8181/cxs/tenants \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>" \
-  -d '{"id": "new-tenant"}'
+  --user karaf:karaf \
+  -H "Content-Type: application/json" \
+  -d '{
+    "requestedId": "new-tenant",
+    "properties": {
+      "name": "New Tenant",
+      "description": "Migrated tenant"
+    }
+  }'
 
 # Step 2: Migrate data
 curl -X POST http://localhost:8181/cxs/tenants/migration/default/new-tenant \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>"
+  --user karaf:karaf \
+  -H "Content-Type: application/json"
 ----
 
 === Verification
@@ -498,8 +533,9 @@ After migration, verify data integrity:
 [source,bash]
 ----
 # Check profile count
-curl http://localhost:8181/cxs/tenants/new-tenant/profiles/count \
-  -H "Authorization: Basic <ADMIN_CREDENTIALS>"
+curl -X GET http://localhost:8181/cxs/tenants/new-tenant/profiles/count \
+  --user karaf:karaf \
+  -H "Content-Type: application/json"
 ----
 
 == Working with Events and Rules
@@ -510,9 +546,9 @@ First, create a JSON schema for your custom event type and deploy it using the J
 
 [source,bash]
 ----
-curl --location --request POST 'http://localhost:8181/cxs/jsonSchema' \
--u 'karaf:karaf' \
---header 'Content-Type: application/json' \
+curl -X POST http://localhost:8181/cxs/jsonSchema \
+  --user "TENANT_ID:PRIVATE_KEY" \
+  -H "Content-Type: application/json" \
 --data-raw '{
     "$id": "https://unomi.apache.org/schemas/json/events/purchaseCompleted/1-0-0",
     "$schema": "https://json-schema.org/draft/2019-09/schema",
@@ -572,17 +608,20 @@ You can verify your schema has been deployed by listing all available schemas:
 
 [source,bash]
 ----
-curl -u karaf:karaf http://localhost:8181/cxs/jsonSchema
+curl -X GET http://localhost:8181/cxs/jsonSchema \
+  --user "TENANT_ID:PRIVATE_KEY" \
+  -H "Content-Type: application/json"
 ----
 
+NOTE: Replace `TENANT_ID` and `PRIVATE_KEY` with your actual tenant ID and private API key. Only the Tenant API (`/cxs/tenants`) uses system administrator authentication (`karaf:karaf`).
+
 You can also validate events against your schema using the validation endpoint:
 
 [source,bash]
 ----
-curl --request POST \
-  --url http://localhost:8181/cxs/jsonSchema/validateEvent \
-  --user karaf:karaf \
-  --header 'Content-Type: application/json' \
+curl -X POST http://localhost:8181/cxs/jsonSchema/validateEvent \
+  --user "TENANT_ID:PRIVATE_KEY" \
+  -H "Content-Type: application/json" \
   --data '{
     "eventType": "purchaseCompleted",
     "scope": "myapp",
@@ -644,7 +683,7 @@ Create a rule to update profile properties based on purchase events:
 [source,bash]
 ----
 curl -X POST http://localhost:8181/cxs/rules \
-  -H "Authorization: Basic <BASE64(TENANT_ID:PRIVATE_KEY)>" \
+  --user "TENANT_ID:PRIVATE_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "metadata": {
@@ -720,8 +759,9 @@ curl -X POST http://localhost:8181/cxs/context.json \
 2. Verify profile properties were updated:
 [source,bash]
 ----
-curl http://localhost:8181/cxs/profiles/profile-456 \
-  -H "Authorization: Basic <BASE64(TENANT_ID:PRIVATE_KEY)>"
+curl -X GET http://localhost:8181/cxs/profiles/profile-456 \
+  --user "TENANT_ID:PRIVATE_KEY" \
+  -H "Content-Type: application/json"
 ----
 
 Expected response will show updated properties:
@@ -746,7 +786,7 @@ Create a segment for customers with high total revenue:
 [source,bash]
 ----
 curl -X POST http://localhost:8181/cxs/segments \
-  -H "Authorization: Basic <BASE64(TENANT_ID:PRIVATE_KEY)>" \
+  --user "TENANT_ID:PRIVATE_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "metadata": {
@@ -772,7 +812,7 @@ Create a rule to track days between purchases:
 [source,bash]
 ----
 curl -X POST http://localhost:8181/cxs/rules \
-  -H "Authorization: Basic <BASE64(TENANT_ID:PRIVATE_KEY)>" \
+  --user "TENANT_ID:PRIVATE_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "metadata": {
diff --git a/manual/src/main/asciidoc/patches.adoc b/manual/src/main/asciidoc/patches.adoc
index 6c9e85fb8..9425df560 100644
--- a/manual/src/main/asciidoc/patches.adoc
+++ b/manual/src/main/asciidoc/patches.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_migration_patches]]
 === Migration patches
 
 You may provide patches on any predefined items by simply adding a JSON file in :
diff --git a/manual/src/main/asciidoc/privacy.adoc b/manual/src/main/asciidoc/privacy.adoc
index 91021cb68..f35dc0cc4 100644
--- a/manual/src/main/asciidoc/privacy.adoc
+++ b/manual/src/main/asciidoc/privacy.adoc
@@ -77,4 +77,4 @@ and the `withData` specifies whether the data associated with the profile must b
 
 === Related
 
-You might also be interested in the <<Consent API>> section that describe how to manage profile consents.
+You might also be interested in the <<_consent_api,Consent API>> section that describe how to manage profile consents.
diff --git a/manual/src/main/asciidoc/property-types.adoc b/manual/src/main/asciidoc/property-types.adoc
new file mode 100644
index 000000000..1c7d0c7d9
--- /dev/null
+++ b/manual/src/main/asciidoc/property-types.adoc
@@ -0,0 +1,1561 @@
+//
+// 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.
+//
+
+[[_property_types]]
+== Property Types
+
+Property types define the structure and metadata for properties that can be used in profiles and sessions within Apache Unomi. They specify the data type, display hints (ranges, constraints), default values, and other metadata that help inform UIs and enable rich querying capabilities.
+
+IMPORTANT: Property types are primarily designed for **UI purposes** - they inform user interfaces about what properties should be editable, how they should be displayed, and what constraints apply. Property types are **dynamically created and updated** at runtime and do not enforce strict validation on the server side. For actual data validation, Apache Unomi uses <<_json_schemas,JSON Schemas>>, which are used exclusively for validating events sent through public endpoints.
+
+==== Quick Reference: Property Types vs JSON Schemas
+
+|===
+| Aspect | Property Types | JSON Schemas
+
+| **Primary Purpose** | UI metadata and display hints | Server-side validation
+
+| **Used For Objects** | Profiles (editing), Sessions (editing) | Events (validation only)
+
+| **Storage** | Stored as PropertyType items, accessible via REST API | Stored in Elasticsearch/OpenSearch
+
+| **Dynamic Creation** | Yes, can be created/updated at runtime via REST API | Yes, can be added via API but primarily for events
+
+| **Validation** | No server-side validation (informational only) | Yes, enforces strict validation
+
+| **Event Support** | Not applicable - property types are for profiles and sessions only | Required for all events sent through public endpoints
+
+| **Accessibility** | Accessible via `/cxs/profiles/properties/targets/{target}` REST API | Accessible via JSON schema API
+
+|===
+
+=== Overview
+
+Property types serve as **informational schemas** for properties, primarily used by UIs to:
+
+* The data type (string, integer, date, boolean, etc.)
+* Whether the property can have multiple values
+* Default values
+* Validation constraints (ranges, date ranges, IP ranges) - primarily for UI hints
+* Which object types the property applies to (profiles or sessions)
+* How properties should be merged when profiles are combined
+* Whether the property is protected (read-only)
+* Display metadata (names, descriptions, tags, ranks) for UI organization
+
+=== Property Type Targets
+
+Property types are organized by their `target`, which indicates which type of object the property applies to:
+
+* `profiles` or `profile` - Properties for Profile objects (primary use case: editing profile data in UIs)
+* `sessions` or `session` - Properties for Session objects (primary use case: editing session data in UIs)
+
+The target is typically determined automatically from the file path when property types are loaded from JSON files:
+
+* Files in `/META-INF/cxs/properties/profiles/...` → target = `"profiles"`
+* Files in `/META-INF/cxs/properties/sessions/...` → target = `"sessions"`
+
+NOTE: Property types are only used for profiles and sessions. Events are immutable records and should not be edited through property type-based UIs. Event validation is handled by JSON schemas, not property types.
+
+=== Property Type Structure
+
+A property type is defined using the following structure:
+
+==== Structure Definition
+
+Inherits all the fields from: <<MetadataItem>>
+
+|===
+| *Field name* | *Type* | *Description*
+
+| target | String | The type of object this property type applies to (e.g., "profiles", "sessions"). Determined automatically from file path if not explicitly set. The target is extracted from the directory name immediately following "properties" in the file path (e.g., `META-INF/cxs/properties/profiles/...` → `"profiles"`).
+
+| type / valueTypeId | String | The identifier of the value type constraining values for properties using this PropertyType (e.g., "string", "integer", "date", "boolean", "set").
+
+| defaultValue | String | The default value that properties using this PropertyType will use if no value is specified explicitly.
+
+| multivalued | Boolean | Whether properties using this property type are multi-valued (a vector of values as opposed to a scalar value).
+
+| protected / protekted | Boolean | Whether properties with this type are marked as protected. Protected properties can be displayed but their value cannot be changed. Note: In JSON files, use `"protected"` (the Java field name is `protekted`).
+
+| rank | Double | The rank of this PropertyType for ordering purposes. Used to control the display order of properties in UIs.
+
+| mergeStrategy | String | The identifier of the PropertyMergeStrategyType to be used when profiles with properties using this PropertyType are being merged.
+
+| dateRanges | List<DateRange> | Optional list of date ranges that can be used for UI categorization and hints. Note: These are informational for UIs, not enforced server-side validation.
+
+| numericRanges | List<NumericRange> | Optional list of numeric ranges that can be used for UI categorization and hints (e.g., age groups). Note: These are informational for UIs, not enforced server-side validation.
+
+| ipRanges | List<IpRange> | Optional list of IP ranges that can be used for UI categorization and hints. Note: These are informational for UIs, not enforced server-side validation.
+
+| automaticMappingsFrom | Set<String> | Set of property names from which properties of this type would be automatically initialized from (legacy feature).
+
+| childPropertyTypes | Set<PropertyType> | For nested/complex properties, this contains the child property types that define the structure.
+
+|===
+
+==== Metadata Fields
+
+Property types inherit from MetadataItem, which provides:
+
+|===
+| *Field name* | *Type* | *Description*
+
+| id | String | Unique identifier for the property type (usually matches the property name).
+
+| name | String | Display name for the property type.
+
+| description | String | Description of what the property represents.
+
+| scope | String | The scope for the property type.
+
+| tags | Set<String> | User-editable tags for categorization.
+
+| systemTags | Set<String> | System-reserved tags for categorization (e.g., "profileProperties", "sessionProperties", "personalIdentifierProperties").
+
+| enabled | Boolean | Whether the property type is enabled.
+
+| hidden | Boolean | Whether the property type should be hidden in UIs.
+
+| readOnly | Boolean | Whether the property type definition can be edited.
+
+|===
+
+=== Value Types
+
+Property types use value types to define the primitive data type. Common value types include:
+
+* `string` - Text values
+* `integer` - Whole numbers
+* `long` - Large integers
+* `float` - Floating point numbers
+* `date` - Date and time values
+* `boolean` - True/false values
+* `set` - Collections of values (for multi-valued or nested properties)
+* `email` - Email addresses
+* `geoPoint` - Geographic coordinates
+
+=== Examples
+
+==== Profile Property Type Example
+
+This example shows a profile property type for storing a person's age with numeric ranges:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "age",
+    "name": "Age",
+    "systemTags": [
+      "properties",
+      "profileProperties",
+      "personalProfileProperties"
+    ]
+  },
+  "type": "integer",
+  "defaultValue": "",
+  "numericRanges": [
+    {"key": "*_10", "to": 10},
+    {"key": "10_20", "from": 10, "to": 20},
+    {"key": "20_30", "from": 20, "to": 30},
+    {"key": "30_40", "from": 30, "to": 40},
+    {"key": "40_50", "from": 40, "to": 50},
+    {"key": "50_*", "from": 50}
+  ],
+  "automaticMappingsFrom": [],
+  "rank": "501.0"
+}
+----
+
+==== Session Property Type Example
+
+This example shows a session property type for storing geographic information:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "sessionCity",
+    "name": "City",
+    "systemTags": [
+      "properties",
+      "sessionProperties",
+      "geographicSessionProperties"
+    ]
+  },
+  "type": "string",
+  "defaultValue": "",
+  "automaticMappingsFrom": [],
+  "rank": "3.0"
+}
+----
+
+==== Simple Profile Property Type Example
+
+This example shows a basic profile property type for storing a first name:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "firstName",
+    "name": "First name",
+    "systemTags": [
+      "properties",
+      "profileProperties",
+      "basicProfileProperties",
+      "personalIdentifierProperties"
+    ]
+  },
+  "type": "string",
+  "defaultValue": "",
+  "automaticMappingsFrom": [
+    "j:firstName"
+  ],
+  "rank": "101.0"
+}
+----
+
+=== Dynamic Creation and Management
+
+Property types are designed to be **dynamically created and updated at runtime**. This makes them ideal for scenarios where property definitions need to change without code deployments or server restarts.
+
+==== Key Characteristics
+
+* **Runtime Creation**: Property types can be created, updated, and deleted via REST API or GraphQL without restarting the server
+* **No Code Deployment Required**: Changes to property types take effect immediately
+* **UI-Driven**: Primarily used to inform UIs about property structure and constraints
+* **Flexible**: Can be modified to adapt to changing business requirements
+* **Multi-tenant**: Property types can be scoped to specific tenants
+
+==== Use Cases for Dynamic Property Types
+
+* **Custom Fields**: Allow users to define custom profile or session properties through a UI
+* **A/B Testing**: Quickly add or modify property definitions for testing
+* **Configuration-Driven UIs**: Build forms and property editors that adapt to property type definitions
+* **Integration Flexibility**: Add properties for new integrations without code changes
+* **Business Rule Changes**: Update property constraints and metadata as business rules evolve
+
+=== Creating Property Types
+
+Property types can be created in several ways:
+
+==== Via JSON Files in Plugins
+
+The most common way is to include property type definitions as JSON files in your plugin bundle:
+
+1. Create JSON files in your plugin's resources directory:
+   * Profile properties: `META-INF/cxs/properties/profiles/...`
+   * Session properties: `META-INF/cxs/properties/sessions/...`
+
+2. The target is automatically determined from the directory structure:
+   * Files in `properties/profiles/` → target = `"profiles"`
+   * Files in `properties/sessions/` → target = `"sessions"`
+
+3. Subdirectories can be used for organization (e.g., `profiles/personal/`, `profiles/contact/`)
+
+==== Via REST API
+
+Property types can be created or updated using the REST API:
+
+[source,http]
+----
+POST /cxs/profiles/properties
+Content-Type: application/json
+
+{
+  "metadata": {
+    "id": "customProperty",
+    "name": "Custom Property",
+    "systemTags": ["properties", "profileProperties"]
+  },
+  "type": "string",
+  "defaultValue": "",
+  "target": "profiles",
+  "rank": "100.0"
+}
+----
+
+==== Via GraphQL API
+
+Property types can also be managed through the GraphQL API using property type mutations and queries.
+
+=== Querying Property Types
+
+==== Get All Property Types by Target
+
+Retrieve all property types for a specific target:
+
+[source,http]
+----
+GET /cxs/profiles/properties/targets/profiles
+----
+
+Response:
+[source,json]
+----
+[
+  {
+    "metadata": {
+      "id": "firstName",
+      "name": "First name",
+      ...
+    },
+    "type": "string",
+    ...
+  },
+  ...
+]
+----
+
+==== Get All Property Types
+
+Retrieve all property types grouped by target:
+
+[source,http]
+----
+GET /cxs/profiles/properties
+----
+
+Response:
+[source,json]
+----
+{
+  "profiles": [...],
+  "sessions": [...]
+  // Note: Event property types are NOT included here as they are not stored as PropertyType items
+}
+----
+
+==== Get Property Type by ID
+
+Retrieve a specific property type:
+
+[source,http]
+----
+GET /cxs/profiles/properties/firstName
+----
+
+==== Get Property Types by Tag
+
+Retrieve property types with specific tags:
+
+[source,http]
+----
+GET /cxs/profiles/properties/tags/profileProperties,personalProfileProperties
+----
+
+==== Get Property Types by System Tag
+
+Retrieve property types with specific system tags:
+
+[source,http]
+----
+GET /cxs/profiles/properties/systemTags/profileProperties
+----
+
+=== Property Type Features
+
+==== Multi-valued Properties
+
+Set `multivalued` to `true` to allow a property to contain multiple values:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "interests",
+    "name": "Interests"
+  },
+  "type": "string",
+  "multivalued": true,
+  "rank": "200.0"
+}
+----
+
+==== Protected Properties
+
+Set `protected` to `true` to make a property read-only (note: use `"protected"` in JSON, not `"protekted"`):
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "systemId",
+    "name": "System ID"
+  },
+  "type": "string",
+  "protected": true,
+  "rank": "1.0"
+}
+----
+
+==== Numeric Ranges
+
+Define ranges for numeric properties to enable categorization:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "income",
+    "name": "Income"
+  },
+  "type": "integer",
+  "numericRanges": [
+    {"key": "low", "to": 30000},
+    {"key": "medium", "from": 30000, "to": 100000},
+    {"key": "high", "from": 100000}
+  ]
+}
+----
+
+==== Date Ranges
+
+Define ranges for date properties:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "registrationDate",
+    "name": "Registration Date"
+  },
+  "type": "date",
+  "dateRanges": [
+    {"key": "recent", "from": "2024-01-01"},
+    {"key": "old", "to": "2023-12-31"}
+  ]
+}
+----
+
+==== Merge Strategies
+
+Specify how properties should be merged when profiles are combined:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "lastLoginDate",
+    "name": "Last Login Date"
+  },
+  "type": "date",
+  "mergeStrategy": "mostRecentMergeStrategy",
+  "rank": "300.0"
+}
+----
+
+Common merge strategies include:
+* `defaultMergeStrategy` - Default merge behavior (typically uses the first non-null value)
+* `mostRecentMergeStrategy` - Use the most recent value (for dates and timestamps)
+* `oldestMergeStrategy` - Use the oldest value (for dates and timestamps)
+* `addMergeStrategy` - Add values together (for numeric types)
+* `nonEmptyMergeStrategy` - Prefer non-empty values
+
+NOTE: The merge strategy identifier in property type JSON files should match the `id` field from the merge strategy definition JSON files located in the `META-INF/cxs/mergers/` directory (this is a file system path within plugin bundles, not an API endpoint).
+
+==== Nested Properties
+
+For complex objects, use `childPropertyTypes` to define nested structures:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "address",
+    "name": "Address"
+  },
+  "type": "set",
+  "childPropertyTypes": [
+    {
+      "metadata": {
+        "id": "street",
+        "name": "Street"
+      },
+      "type": "string"
+    },
+    {
+      "metadata": {
+        "id": "city",
+        "name": "City"
+      },
+      "type": "string"
+    },
+    {
+      "metadata": {
+        "id": "zipCode",
+        "name": "Zip Code"
+      },
+      "type": "string"
+    }
+  ]
+}
+----
+
+=== Tags and System Tags
+
+Property types support two types of tags for categorization: `tags` and `systemTags`. Understanding the difference between them is important for organizing and filtering property types in UIs.
+
+==== Tags vs System Tags
+
+**Tags** (`tags` field):
+* User-editable tags that can be modified through UIs
+* Intended for custom categorization and organization
+* Can be added, removed, or changed by end users
+* Perfect for creating custom groupings for UI display
+* Example use cases: grouping properties by department, project, or custom business logic
+
+**System Tags** (`systemTags` field):
+* Reserved tags typically populated through JSON descriptors
+* Not meant to be modified by end users
+* Used for system-level categorization and filtering
+* Help classify properties for internal system logic
+* Example: `profileProperties`, `sessionProperties`, `personalIdentifierProperties`
+
+==== Using Tags to Group Properties in UIs
+
+Tags provide a flexible way to organize property types for display and editing in user interfaces. Here's how you can leverage tags:
+
+===== UI Grouping Strategy
+
+1. **Create Custom Tags**: Assign custom tags to property types based on how you want to group them in your UI
+2. **Query by Tags**: Use the REST API to retrieve property types filtered by specific tags
+3. **Display in Groups**: Organize properties in tabs, sections, or accordions based on their tags
+
+===== Example: Grouping Properties by Department
+
+Suppose you want to group profile properties by department in your UI:
+
+[source,json]
+----
+// Marketing properties
+{
+  "metadata": {
+    "id": "marketingSource",
+    "name": "Marketing Source",
+    "tags": ["marketing", "acquisition"]
+  },
+  "type": "string"
+}
+
+// Sales properties
+{
+  "metadata": {
+    "id": "salesRep",
+    "name": "Sales Representative",
+    "tags": ["sales", "account-management"]
+  },
+  "type": "string"
+}
+
+// Support properties
+{
+  "metadata": {
+    "id": "supportTier",
+    "name": "Support Tier",
+    "tags": ["support", "customer-service"]
+  },
+  "type": "string"
+}
+----
+
+Then in your UI, you can fetch and display properties grouped by tag:
+
+[source,http]
+----
+# Get all marketing properties
+GET /cxs/profiles/properties/tags/marketing
+
+# Get all sales properties
+GET /cxs/profiles/properties/tags/sales
+
+# Get all support properties
+GET /cxs/profiles/properties/tags/support
+----
+
+===== Example: Multi-Tag Filtering
+
+Properties can have multiple tags, allowing for flexible filtering:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "vipCustomer",
+    "name": "VIP Customer",
+    "tags": ["customer-tier", "priority", "billing"]
+  },
+  "type": "boolean"
+}
+----
+
+You can query by multiple tags (comma-separated):
+
+[source,http]
+----
+# Get properties with any of these tags
+GET /cxs/profiles/properties/tags/customer-tier,priority,billing
+----
+
+==== Creating and Assigning Tags
+
+===== Creating Tags
+
+Tags don't need to be pre-registered. Simply assign a tag string to a property type, and it becomes available for filtering. Tags are created implicitly when first used.
+
+===== Assigning Tags via JSON Files
+
+When defining property types in JSON files, include tags in the metadata:
+
+[source,json]
+----
+{
+  "metadata": {
+    "id": "customProperty",
+    "name": "Custom Property",
+    "tags": ["my-custom-tag", "another-tag"],
+    "systemTags": ["properties", "profileProperties"]
+  },
+  "type": "string",
+  "rank": "100.0"
+}
+----
+
+===== Assigning Tags via REST API
+
+You can add or modify tags when creating or updating a property type:
+
+[source,http]
+----
+POST /cxs/profiles/properties
+Content-Type: application/json
+
+{
+  "metadata": {
+    "id": "newProperty",
+    "name": "New Property",
+    "tags": ["custom-group", "editable"],
+    "systemTags": ["properties", "profileProperties"]
+  },
+  "type": "string",
+  "target": "profiles"
+}
+----
+
+===== Updating Tags on Existing Property Types
+
+To add tags to an existing property type, retrieve it, modify the tags, and save it:
+
+[source,http]
+----
+# 1. Get the existing property type
+GET /cxs/profiles/properties/existingProperty
+
+# 2. Update it with new tags
+POST /cxs/profiles/properties
+Content-Type: application/json
+
+{
+  "metadata": {
+    "id": "existingProperty",
+    "name": "Existing Property",
+    "tags": ["existing-tag", "new-tag", "another-tag"],
+    "systemTags": ["properties", "profileProperties"]
+  },
+  "type": "string"
+}
+----
+
+===== Assigning Tags via GraphQL
+
+Tags can also be managed through the GraphQL API when creating or updating property types.
+
+==== Tag-Based UI Organization Examples
+
+===== Example 1: Tabbed Interface
+
+Organize properties into tabs based on tags:
+
+[source,typescript]
+----
+// Fetch properties grouped by tags
+const marketingProps: PropertyType[] = await fetch('/cxs/profiles/properties/tags/marketing')
+  .then(res => res.json());
+const salesProps: PropertyType[] = await fetch('/cxs/profiles/properties/tags/sales')
+  .then(res => res.json());
+const supportProps: PropertyType[] = await fetch('/cxs/profiles/properties/tags/support')
+  .then(res => res.json());
+
+// Display in tabs (pseudo-rendering - in real UI framework, this would be JSX/TSX)
+console.log('Tabs:');
+console.log('  Tab: Marketing');
+console.log('    PropertyEditor with', marketingProps.length, 'properties');
+console.log('  Tab: Sales');
+console.log('    PropertyEditor with', salesProps.length, 'properties');
+console.log('  Tab: Support');
+console.log('    PropertyEditor with', supportProps.length, 'properties');
+----
+
+===== Example 2: Accordion Sections
+
+Group properties in collapsible sections:
+
+[source,typescript]
+----
+const allProps: PropertyType[] = await fetch('/cxs/profiles/properties/targets/profiles')
+  .then(res => res.json());
+
+// Group properties by tag
+function groupByTag(propertyTypes: PropertyType[]): Record<string, PropertyType[]> {
+  const grouped: Record<string, PropertyType[]> = {};
+  for (const pt of propertyTypes) {
+    const tags = pt.metadata.tags || [];
+    for (const tag of tags) {
+      if (!grouped[tag]) {
+        grouped[tag] = [];
+      }
+      grouped[tag].push(pt);
+    }
+  }
+  return grouped;
+}
+
+const grouped = groupByTag(allProps);
+
+// Display in accordion (pseudo-rendering - in real UI framework, this would be JSX/TSX)
+console.log('Accordion:');
+for (const [tag, properties] of Object.entries(grouped)) {
+  console.log(`  AccordionItem: ${tag}`);
+  console.log(`    PropertyEditor with ${properties.length} properties`);
+}
+----
+
+===== Example 3: Filterable List
+
+Allow users to filter properties by tag:
+
+[source,typescript]
+----
+let selectedTag: string | null = null;
+
+const allProps: PropertyType[] = await fetch('/cxs/profiles/properties/targets/profiles')
+  .then(res => res.json());
+
+// Extract unique tags
+function extractUniqueTags(propertyTypes: PropertyType[]): string[] {
+  const tags: string[] = [];
+  for (const pt of propertyTypes) {
+    const propertyTags = pt.metadata.tags || [];
+    for (const tag of propertyTags) {
+      if (!tags.includes(tag)) {
+        tags.push(tag);
+      }
+    }
+  }
+  return tags;
+}
+
+const uniqueTags = extractUniqueTags(allProps);
+
+// Filter properties based on selected tag
+const filteredProps: PropertyType[] = selectedTag
+  ? await fetch(`/cxs/profiles/properties/tags/${selectedTag}`).then(res => res.json())
+  : allProps;
+
+// Display (pseudo-rendering - in real UI framework, this would be JSX/TSX)
+console.log('Select dropdown:');
+console.log('  Option: All Properties');
+for (const tag of uniqueTags) {
+  console.log(`  Option: ${tag}`);
+}
+
+console.log(`PropertyList with ${filteredProps.length} properties`);
+----
+
+==== Best Practices for Tags
+
+1. **Use Descriptive Tag Names**: Choose clear, meaningful tag names (e.g., `marketing`, `sales`, `support` rather than `m`, `s`, `sup`)
+
+2. **Create Hierarchical Tags**: Use dot notation for hierarchical organization (e.g., `department.marketing`, `department.sales`)
+
+3. **Use Consistent Tagging**: Establish a tagging convention and apply it consistently across all property types
+
+4. **Combine Tags and System Tags**: Use system tags for system-level categorization and tags for UI-level organization
+
+5. **Document Tag Conventions**: Maintain documentation about your tagging conventions so team members use tags consistently
+
+6. **Avoid Over-Tagging**: Don't assign too many tags to a single property type - 2-4 tags is usually sufficient
+
+7. **Use Tags for Permissions**: Consider using tags to control which properties are visible or editable by different user roles
+
+=== System Tags
+
+System tags are used to categorize property types. Common system tags include:
+
+* `properties` - General property tag
+* `profileProperties` - Properties for profiles
+* `sessionProperties` - Properties for sessions
+* `basicProfileProperties` - Basic profile information
+* `personalProfileProperties` - Personal information
+* `contactProfileProperties` - Contact information
+* `workProfileProperties` - Work-related information
+* `socialProfileProperties` - Social media identifiers
+* `systemProfileProperties` - System-managed properties (automatically maintained by Unomi)
+* `leadProfileProperties` - Lead management properties
+* `personalIdentifierProperties` - Properties that identify individuals (may be subject to privacy regulations)
+* `geographicSessionProperties` - Geographic session information
+* `technicalSessionProperties` - Technical session information
+
+=== Validation and Property Types
+
+IMPORTANT: Property types provide **informational metadata** for UIs but do **not enforce server-side validation**. The ranges, types, and constraints defined in property types are hints for UI components, not strict validation rules.
+
+==== What Property Types Do
+
+* **Inform UIs**: Tell user interfaces what properties exist, their types, and how to display them
+* **Provide Hints**: Give UI components information about expected data formats and constraints
+* **Enable Dynamic Forms**: Allow UIs to generate forms and property editors automatically
+* **Organize Display**: Help organize properties in UIs using tags, ranks, and categories
+
+==== What Property Types Don't Do
+
+* **Server-Side Validation**: Property types do not validate data on the server
+* **Enforce Constraints**: Ranges and constraints are informational, not enforced
+* **Prevent Invalid Data**: Invalid data can still be stored if not validated elsewhere
+* **Type Safety**: Property types don't guarantee type safety at the storage level
+
+==== When Validation Happens
+
+* **JSON Schemas**: Used exclusively for server-side validation of events sent through `/context.json` and `/eventcollector` endpoints
+* **Property Types**: Provide no server-side validation - they are informational only
+* **UI Validation**: Implement client-side validation in your UI based on property type hints (recommended for profiles and sessions)
+* **Application Logic**: Add validation in your application code if needed for profiles and sessions
+* **Database Constraints**: Use database-level constraints if your persistence layer supports them
+
+==== Best Practice: Property Types for Profiles/Sessions, JSON Schemas for Events
+
+Property types and JSON schemas serve different purposes for different objects:
+
+**For Profiles and Sessions:**
+* Use property types to build UIs for editing profile/session properties
+* Implement client-side validation in your UI based on property type hints
+* Property types provide no server-side validation - data is stored as-is
+
+**For Events:**
+* Use JSON schemas to validate events sent through `/context.json` or `/eventcollector`
+* Event property types are not accessible via REST API (they're generated internally)
+* To understand event structure, query actual events or use JSON schemas
+
+[plantuml]
+----
+@startuml
+skinparam rectangle {
+    BackgroundColor #E8F4F8
+    BorderColor #4A90A4
+}
+
+rectangle "Profiles/Sessions Workflow" {
+    rectangle "Property Type\n(UI hints)" as PT
+    rectangle "UI Form\n(with client validation)" as UI
+    rectangle "Profile/Session Update\n(No server validation)" as Update
+    
+    PT --> UI
+    UI --> Update
+}
+
+rectangle "Events Workflow" {
+    rectangle "JSON Schema\n(validation)" as Schema
+    rectangle "Event sent via\n/context.json\nor /eventcollector" as Event
+    rectangle "Server validates\nvia JSON Schema" as Validate
+    rectangle "Event stored\nif valid" as Store
+    
+    Schema --> Event
+    Event --> Validate
+    Validate --> Store
+}
+@enduml
+----
+
+=== Best Practices
+
+1. **Use descriptive names**: Property type IDs should be clear and descriptive (e.g., `firstName` rather than `fn`).
+
+2. **Set appropriate ranks**: Use the `rank` field to control display order in UIs. Lower numbers appear first.
+
+3. **Use system tags**: Apply appropriate system tags to help categorize and filter property types.
+
+4. **Organize with subdirectories**: Use subdirectories in your plugin structure to organize related property types.
+
+5. **Define ranges for categorization**: Use numeric ranges, date ranges, or IP ranges to enable automatic categorization of values.
+
+6. **Mark sensitive properties**: Use `personalIdentifierProperties` system tag for properties that identify individuals.
+
+7. **Set merge strategies**: Define appropriate merge strategies for properties that may need to be merged when profiles are combined.
+
+8. **Use appropriate value types**: Choose the correct value type (string, integer, date, etc.) for your data.
+
+=== Built-in Property Types
+
+Apache Unomi comes with a comprehensive set of built-in property types that cover common use cases. These are organized by category and target type.
+
+==== Built-in Profile Property Types
+
+===== Basic Profile Properties
+
+These properties store basic identifying information about profiles:
+
+* `firstName` (string) - First name of the profile
+* `lastName` (string) - Last name of the profile
+* `gender` (string) - Gender
+* `nationality` (string) - Nationality
+
+All basic profile properties are tagged with `basicProfileProperties`. `firstName` and `lastName` are also tagged with `personalIdentifierProperties`.
+
+===== Personal Profile Properties
+
+These properties store personal information:
+
+* `age` (integer) - Age with numeric ranges (0-10, 10-20, 20-30, 30-40, 40-50, 50+)
+* `birthDate` (date) - Birth date with date ranges
+* `kids` (integer) - Number of children
+* `maritalStatus` (string) - Marital status
+
+All personal profile properties are tagged with `personalProfileProperties`.
+
+===== Contact Profile Properties
+
+These properties store contact information:
+
+* `email` (email) - Email address
+* `phoneNumber` (string) - Phone number
+* `address` (string) - Street address
+* `city` (string) - City
+* `zipCode` (string) - Zip/postal code
+* `countryName` (string) - Country name
+
+All contact profile properties are tagged with `contactProfileProperties`. Email, address, and phoneNumber are also tagged with `personalIdentifierProperties`.
+
+===== Work Profile Properties
+
+These properties store work-related information:
+
+* `company` (string) - Company name
+* `jobTitle` (string) - Job title
+* `income` (integer) - Income
+
+All work profile properties are tagged with `workProfileProperties`.
+
+===== Social Profile Properties
+
+These properties store social media identifiers:
+
+* `facebookId` (string) - Facebook ID
+* `twitterId` (string) - Twitter ID
+* `linkedInId` (string) - LinkedIn ID
+* `googleId` (string) - Google ID
+
+All social profile properties are tagged with `socialProfileProperties`.
+
+===== System Profile Properties
+
+These properties are automatically managed by Unomi and are typically protected (read-only):
+
+* `firstVisit` (date) - Date of first visit (protected, uses `oldestMergeStrategy`)
+* `lastVisit` (date) - Date of last visit (protected, uses `mostRecentMergeStrategy`)
+* `previousVisit` (date) - Date of previous visit (protected, uses `mostRecentMergeStrategy`)
+* `nbOfVisits` (integer) - Number of visits with ranges (protected, uses `addMergeStrategy`)
+* `totalNbOfVisits` (integer) - Total number of visits (protected, uses `addMergeStrategy`)
+
+All system profile properties are tagged with `systemProfileProperties`.
+
+===== Lead Profile Properties
+
+* `leadAssignedTo` (string) - Person assigned to the lead
+
+All lead profile properties are tagged with `leadProfileProperties`.
+
+==== Built-in Session Property Types
+
+===== Geographic Session Properties
+
+These properties store geographic information about the session:
+
+* `sessionCity` (string) - City where the session occurred
+* `sessionCountryName` (string) - Country name
+* `sessionCountryCode` (string) - Country code
+* `sessionAdminSubDiv1` (string) - First-level administrative subdivision (e.g., state, province)
+* `sessionAdminSubDiv2` (string) - Second-level administrative subdivision (e.g., county)
+* `latitude` (string) - Latitude coordinate
+* `longitude` (string) - Longitude coordinate
+
+All geographic session properties are tagged with `geographicSessionProperties`.
+
+===== Technical Session Properties
+
+These properties store technical information about the session:
+
+* `deviceCategory` (string) - Device category (e.g., desktop, mobile, tablet)
+* `operatingSystemName` (string) - Operating system name
+* `operatingSystemFamily` (string) - Operating system family
+* `userAgentName` (string) - User agent name (browser name)
+* `userAgentVersion` (string) - User agent version (browser version)
+* `pageReferringURL` (string) - URL of the referring page
+
+All technical session properties are tagged with `technicalSessionProperties`.
+
+==== Property Type Organization
+
+Built-in property types are organized in the following directory structure:
+
+[source]
+----
+META-INF/cxs/properties/
+  profiles/
+    basic/          # Basic identifying information
+    personal/       # Personal information
+    contact/        # Contact information
+    work/           # Work-related information
+    social/         # Social media identifiers
+    system/         # System-managed properties
+    lead/           # Lead management
+  sessions/
+    geographic/     # Geographic information
+    technical/      # Technical information
+----
+
+The directory structure helps organize property types, and the target is automatically determined from the parent directory (`profiles` or `sessions`).
+
+==== Viewing Built-in Property Types
+
+You can view all built-in property types using the REST API:
+
+[source,http]
+----
+# Get all profile property types
+GET /cxs/profiles/properties/targets/profiles
+
+# Get all session property types
+GET /cxs/profiles/properties/targets/sessions
+
+# Get property types by system tag
+GET /cxs/profiles/properties/systemTags/profileProperties
+GET /cxs/profiles/properties/systemTags/sessionProperties
+----
+
+=== Property Types vs JSON Schemas
+
+Property types and JSON schemas serve complementary but distinct roles in Apache Unomi:
+
+==== Property Types: UI-Focused Metadata
+
+Property types are:
+* **Primarily for UIs**: Inform user interfaces about property structure, display names, types, and constraints
+* **Dynamically managed**: Can be created, updated, and deleted at runtime via REST API or GraphQL
+* **Informational**: Provide metadata about properties but don't enforce strict server-side validation
+* **Flexible**: Allow UIs to adapt to changing property definitions without code changes
+* **Target-specific**: Organized by target (profiles and sessions)
+
+Use property types when you need to:
+* Build dynamic forms and property editors in UIs
+* Display property information to users
+* Organize properties by tags or categories
+* Control property visibility and editability in interfaces
+* Provide hints about data types and constraints to UI components
+
+==== JSON Schemas: Server-Side Validation
+
+JSON schemas are:
+* **For validation**: Enforce strict data validation on the server side
+* **Event-only**: Used exclusively to validate events sent through public endpoints (`/context.json` and `/eventcollector`)
+* **Standard-based**: Use the JSON Schema standard for validation
+* **Persistent**: Stored in Elasticsearch/OpenSearch and loaded at startup
+* **Required for events**: Each event type must have an associated JSON schema with target `"events"`
+
+NOTE: While JSON schemas technically support targets like "profiles", "sessions", "rules", and "segments", in practice they are **only used for event validation**. The validation code only processes schemas with target `"events"` when validating incoming requests through the public endpoints.
+
+Use JSON schemas when you need to:
+* Validate incoming events from external sources
+* Ensure event data integrity and type safety
+* Enforce business rules and constraints on events
+* Validate event structures before processing
+
+==== How They Work Together
+
+Property types and JSON schemas complement each other:
+
+[plantuml]
+----
+@startuml
+skinparam rectangle {
+    BackgroundColor #E8F4F8
+    BorderColor #4A90A4
+}
+
+skinparam note {
+    BackgroundColor #FFF9E6
+    BorderColor #D4A574
+}
+
+rectangle "Property Types" as PT {
+    note right
+        • UI metadata (names, descriptions, types)
+        • Display hints (ranks, tags, protected flags)
+        • Dynamic and editable at runtime
+        • Used by GraphQL to generate schema
+    end note
+}
+
+rectangle "User Interface" as UI {
+    note right
+        • Dynamic forms based on property types
+        • Property editors with type hints
+        • Grouped displays using tags
+    end note
+}
+
+rectangle "JSON Schemas" as JSON {
+    note right
+        • Server-side validation for EVENTS ONLY
+        • Event type checking and constraints
+        • Event structure validation
+        • Event data integrity enforcement
+        • Used when events sent via /context.json
+          or /eventcollector endpoints
+    end note
+}
+
+PT -->|"UI Generation"| UI
+UI -->|"Data Submission"| JSON
+@enduml
+----
+
+**Example Workflow:**
+
+1. **Property Type Definition**: A property type defines `email` as a string with description "Email address" for profiles
+2. **UI Generation**: The UI uses the property type to render an email input field with appropriate validation hints for profile editing
+3. **User Input**: User enters an email address in the UI
+4. **Data Storage**: Data is stored in the profile (property types don't validate, but UI can implement client-side validation)
+5. **Event Validation (separate)**: When events are sent through `/context.json` or `/eventcollector`, JSON schemas validate the event structure (not profile properties)
+
+==== When to Use Each
+
+**Use Property Types for:**
+* Building dynamic property editors
+* Organizing properties in UIs (tabs, sections, filters)
+* Providing type hints to form builders
+* Controlling property visibility and editability
+* GraphQL schema generation
+
+**Use JSON Schemas for:**
+* Validating incoming events from external sources (the only actual use case)
+* Enforcing event data type constraints
+* Validating complex nested event structures
+* Ensuring event data integrity on the server
+
+**Use Both When:**
+* You want UI hints for profiles/sessions (property types) AND need to validate events (JSON schemas)
+* Building UIs that display profile/session data (property types) while also handling event validation (JSON schemas)
+
+=== Property Types for Events
+
+Property types are **not used for events**. Events are immutable records of user interactions and should not be edited through property type-based UIs.
+
+If you need to understand event structure for display purposes:
+* Query actual events to see their structure
+* Use JSON schemas (with target `"events"`) to understand the expected structure of events
+* JSON schemas define the validation rules for events sent through public endpoints
+
+Event validation is performed by JSON schemas (with target `"events"`) when events are sent through the public endpoints (`/context.json` and `/eventcollector`).
+
+=== Building UIs with Property Types
+
+Property types are designed to enable dynamic UI generation. Here's how to use them effectively:
+
+==== Step 1: Fetch Property Types
+
+Retrieve property types for your target (profiles or sessions):
+
+[source]
+----
+# Fetch all profile property types
+GET /cxs/profiles/properties/targets/profiles
+
+# Fetch session property types
+GET /cxs/profiles/properties/targets/sessions
+
+# Fetch by tag for grouping
+GET /cxs/profiles/properties/tags/marketing
+----
+
+TypeScript example:
+
+[source,typescript]
+----
+// Fetch property types from REST API
+const propertyTypes: PropertyType[] = await fetch('/cxs/profiles/properties/targets/profiles')
+  .then(res => res.json());
+
+// Or fetch by tag
+const marketingProps: PropertyType[] = await fetch('/cxs/profiles/properties/tags/marketing')
+  .then(res => res.json());
+----
+
+==== Step 2: Generate Form Fields
+
+Use property type metadata to generate appropriate form fields:
+
+[source,typescript]
+----
+interface FormField {
+  id: string;
+  name: string;
+  description?: string;
+  inputType: string;
+  multivalued: boolean;
+  defaultValue: string;
+  readOnly: boolean;
+  tags: string[];
+}
+
+function generateFormField(propertyType: PropertyType): FormField {
+  // Extract property type information
+  const id = propertyType.metadata.id;
+  const name = propertyType.metadata.name;
+  const description = propertyType.metadata.description;
+  const valueType = propertyType.type;
+  const isMultivalued = propertyType.multivalued || false;
+  const defaultValue = propertyType.defaultValue || '';
+  const isProtected = propertyType.protected || false;
+  
+  // Determine input type based on value type
+  let inputType: string;
+  if (valueType === 'integer' || valueType === 'long') {
+    inputType = 'number';
+  } else if (valueType === 'date') {
+    inputType = 'date';
+  } else if (valueType === 'boolean') {
+    inputType = 'checkbox';
+  } else if (valueType === 'email') {
+    inputType = 'email';
+  } else {
+    inputType = 'text';
+  }
+  
+  // Return field configuration
+  return {
+    id,
+    name,
+    description,
+    inputType,
+    multivalued: isMultivalued,
+    defaultValue,
+    readOnly: isProtected,
+    tags: propertyType.metadata.tags || []
+  };
+}
+
+// Generate form fields for all property types
+const formFields: FormField[] = propertyTypes.map(generateFormField);
+----
+
+==== Step 3: Render Dynamic Forms
+
+Use the generated fields to render your form:
+
+[source,typescript]
+----
+interface PropertyFormProps {
+  propertyTypes: PropertyType[];
+  onSubmit: (values: Record<string, any>) => void;
+}
+
+function renderPropertyForm({ propertyTypes, onSubmit }: PropertyFormProps): void {
+  // Initialize form values
+  const values: Record<string, any> = {};
+  
+  // Generate form fields
+  const fields: FormField[] = propertyTypes.map(generateFormField);
+  
+  // Group fields by tags
+  const groupedFields: Record<string, FormField[]> = {};
+  for (const field of fields) {
+    const tag = field.tags[0] || 'other';
+    if (!groupedFields[tag]) {
+      groupedFields[tag] = [];
+    }
+    groupedFields[tag].push(field);
+  }
+  
+  // Render form (pseudo-rendering logic)
+  for (const [tag, tagFields] of Object.entries(groupedFields)) {
+    // Render fieldset with legend
+    console.log(`Fieldset: ${tag}`);
+    
+    for (const field of tagFields) {
+      // Render label
+      console.log(`Label: ${field.name}`);
+      
+      if (field.description) {
+        // Render help-text
+        console.log(`Help: ${field.description}`);
+      }
+      
+      if (field.multivalued) {
+        // Render multi-value-input
+        const currentValue = values[field.id] || [];
+        // onChange handler would update values[field.id] = newValue
+        console.log(`Multi-value input: ${field.inputType}`, currentValue);
+      } else {
+        // Render single input
+        const currentValue = values[field.id] ?? field.defaultValue;
+        // onChange handler would update values[field.id] = newValue
+        console.log(`Input: ${field.inputType}`, currentValue, `readOnly: ${field.readOnly}`);
+      }
+    }
+  }
+  
+  // Render submit button
+  console.log('Submit button: Save');
+}
+----
+
+==== Step 4: Handle Numeric Ranges
+
+For properties with numeric ranges, you can provide range-based inputs:
+
+[source,typescript]
+----
+interface NumericRange {
+  key: string;
+  from?: number;
+  to?: number;
+}
+
+function renderNumericRangeInput(
+  propertyType: PropertyType,
+  value: string,
+  onChange: (value: string) => void
+): void {
+  const numericRanges = propertyType.numericRanges;
+  
+  if (numericRanges && numericRanges.length > 0) {
+    // Render as select dropdown with range options
+    console.log('Select dropdown:');
+    console.log('  Option: Select range');
+    
+    for (const range of numericRanges) {
+      const label = formatRange(range);
+      console.log(`  Option: ${label} (value: ${range.key})`);
+    }
+  } else {
+    // Fallback to regular number input
+    console.log(`Number input: ${value}`);
+  }
+}
+
+function formatRange(range: NumericRange): string {
+  if (range.from !== undefined && range.to !== undefined) {
+    return `${range.from} - ${range.to}`;
+  } else if (range.from !== undefined) {
+    return `${range.from}+`;
+  } else if (range.to !== undefined) {
+    return `up to ${range.to}`;
+  } else {
+    return range.key;
+  }
+}
+----
+
+==== Step 5: Sort by Rank
+
+Use the `rank` field to control display order:
+
+[source,typescript]
+----
+// Sort property types by rank (lower numbers first)
+function sortByRank(propertyTypes: PropertyType[]): PropertyType[] {
+  return [...propertyTypes].sort((a, b) => {
+    const rankA = a.rank ?? 999;  // Default rank for items without rank
+    const rankB = b.rank ?? 999;
+    return rankA - rankB;
+  });
+}
+
+const sortedPropertyTypes: PropertyType[] = sortByRank(propertyTypes);
+----
+
+==== Complete Example: Dynamic Property Editor
+
+Here's a complete example of a dynamic property editor:
+
+[source,typescript]
+----
+interface PropertyType {
+  metadata: {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    systemTags?: string[];
+  };
+  type: string;
+  defaultValue?: string;
+  multivalued?: boolean;
+  protected?: boolean;
+  rank?: number;
+  numericRanges?: NumericRange[];
+}
+
+interface DynamicPropertyEditorState {
+  propertyTypes: PropertyType[];
+  values: Record<string, any>;
+  selectedTag: string | null;
+}
+
+async function createDynamicPropertyEditor(
+  target: string,
+  onSave: (values: Record<string, any>) => void
+): Promise<DynamicPropertyEditorState> {
+  // Initialize state
+  let propertyTypes: PropertyType[] = [];
+  const values: Record<string, any> = {};
+  let selectedTag: string | null = null;
+  
+  // Fetch property types from REST API
+  propertyTypes = await fetch(`/cxs/profiles/properties/targets/${target}`)
+    .then(res => res.json());
+  
+  // Initialize values with defaults
+  for (const propertyType of propertyTypes) {
+    if (propertyType.defaultValue != null) {
+      values[propertyType.metadata.id] = propertyType.defaultValue;
+    }
+  }
+  
+  // Get unique tags for filtering
+  const tags: string[] = [];
+  for (const propertyType of propertyTypes) {
+    const propertyTags = propertyType.metadata.tags || [];
+    for (const tag of propertyTags) {
+      if (!tags.includes(tag)) {
+        tags.push(tag);
+      }
+    }
+  }
+  
+  // Filter property types by selected tag
+  let filteredTypes = propertyTypes;
+  if (selectedTag != null) {
+    filteredTypes = propertyTypes.filter(pt => 
+      (pt.metadata.tags || []).includes(selectedTag!)
+    );
+  }
+  
+  // Sort by rank
+  const sortedTypes = sortByRank(filteredTypes);
+  
+  // Render form (pseudo-rendering - in real UI framework, this would be JSX/TSX)
+  console.log('Rendering form...');
+  
+  // Tag filter dropdown
+  if (tags.length > 0) {
+    console.log('Tag filter dropdown:', selectedTag);
+    console.log('  Option: All properties');
+    for (const tag of tags) {
+      console.log(`  Option: ${tag}`);
+    }
+  }
+  
+  // Property fields
+  for (const propertyType of sortedTypes) {
+    const fieldId = propertyType.metadata.id;
+    const fieldValue = values[fieldId] ?? propertyType.defaultValue ?? '';
+    
+    console.log(`Field: ${propertyType.metadata.name} (${fieldId})`);
+    
+    if (propertyType.metadata.description) {
+      console.log(`  Description: ${propertyType.metadata.description}`);
+    }
+    
+    if (propertyType.protected) {
+      console.log(`  Input: text, value: ${fieldValue}, readOnly: true`);
+    } else {
+      propertyInput(propertyType, fieldValue, (newValue) => {
+        values[fieldId] = newValue;
+      });
+    }
+  }
+  
+  // Submit button
+  console.log('Submit button: Save Properties');
+  
+  return { propertyTypes, values, selectedTag };
+}
+
+function propertyInput(
+  propertyType: PropertyType,
+  value: any,
+  onChange: (value: any) => void
+): void {
+  // Handle numeric ranges
+  if (propertyType.numericRanges && propertyType.numericRanges.length > 0) {
+    console.log('  Select dropdown with numeric ranges');
+    console.log('    Option: Select...');
+    for (const range of propertyType.numericRanges) {
+      console.log(`    Option: ${formatRange(range)} (value: ${range.key})`);
+    }
+    return;
+  }
+  
+  // Handle multivalued properties
+  if (propertyType.multivalued) {
+    const valueList: any[] = Array.isArray(value) ? value : (value ? [value] : []);
+    console.log('  Multi-value input container:');
+    for (let index = 0; index < valueList.length; index++) {
+      const val = valueList[index];
+      const inputType = getInputType(propertyType.type);
+      console.log(`    Input[${index}]: ${inputType}, value: ${val}`);
+      // onChange would update valueList[index] = newVal, then call onChange(valueList)
+    }
+    console.log('    Button: Add Value');
+    return;
+  }
+  
+  // Regular single-value input
+  const inputType = getInputType(propertyType.type);
+  console.log(`  Input: ${inputType}, value: ${value}`);
+}
+
+function getInputType(valueType: string): string {
+  if (valueType === 'integer' || valueType === 'long') {
+    return 'number';
+  } else if (valueType === 'date') {
+    return 'date';
+  } else if (valueType === 'boolean') {
+    return 'checkbox';
+  } else if (valueType === 'email') {
+    return 'email';
+  } else {
+    return 'text';
+  }
+}
+----
+
+=== Related Topics
+
+* <<_data_model_overview,Data Model Overview>> - Learn about the overall data model
+* <<_writing_plugins,Writing Plugins>> - Learn how to create plugins with property types
+* <<_json_schemas,JSON Schemas>> - Learn about JSON schema support in Unomi
+* <<_graphql_api,GraphQL API>> - Learn about GraphQL property type operations
diff --git a/manual/src/main/asciidoc/queries-and-aggregations.adoc b/manual/src/main/asciidoc/queries-and-aggregations.adoc
index 581da18dc..aa536a03c 100644
--- a/manual/src/main/asciidoc/queries-and-aggregations.adoc
+++ b/manual/src/main/asciidoc/queries-and-aggregations.adoc
@@ -28,7 +28,7 @@ Here's an example of a query:
 [source,bash]
 ----
 curl -X POST http://localhost:8181/cxs/query/profile/count \
---user karaf:karaf \
+--user "TENANT_ID:PRIVATE_KEY" \
 -H "Content-Type: application/json" \
 -d @- <<'EOF'
 {
@@ -80,7 +80,7 @@ Here's an example request that uses the `sum` and `avg` metrics:
 [source]
 ----
 curl -X POST http://localhost:8181/cxs/query/session/profile.properties.nbOfVisits/sum/avg \
---user karaf:karaf \
+--user "TENANT_ID:PRIVATE_KEY" \
 -H "Content-Type: application/json" \
 -d @- <<'EOF'
 {
@@ -139,7 +139,7 @@ Here's an example of a request to retrieve a histogram of by day of all the sess
 [source]
 ----
 curl -X POST http://localhost:8181/cxs/query/session/timeStamp \
---user karaf:karaf \
+--user "TENANT_ID:PRIVATE_KEY" \
 -H "Content-Type: application/json" \
 -d @- <<'EOF'
 {
@@ -205,7 +205,7 @@ below:
 [source,shell script]
 ----
 curl -X POST http://localhost:8181/cxs/query/profile/properties.birthDate \
---user karaf:karaf \
+--user "TENANT_ID:PRIVATE_KEY" \
 -H "Content-Type: application/json" \
 -d @- <<'EOF'
 {
@@ -284,7 +284,7 @@ Here's an example of a using numeric range to regroup profiles by number of visi
 [source,shell script]
 ----
 curl -X POST http://localhost:8181/cxs/query/profile/properties.nbOfVisits \
---user karaf:karaf \
+--user "TENANT_ID:PRIVATE_KEY" \
 -H "Content-Type: application/json" \
 -d @- <<'EOF'
 {
@@ -362,7 +362,7 @@ To start a scroll query, use the search endpoint with the following parameters:
 ----
 # Initial scroll query
 curl -X POST http://localhost:8181/cxs/profiles/search \
---user karaf:karaf \
+--user "TENANT_ID:PRIVATE_KEY" \
 -H "Content-Type: application/json" \
 -d @- <<'EOF'
 {
@@ -394,7 +394,7 @@ To retrieve subsequent batches, only the scroll identifier and validity are need
 ----
 # Retrieve next batch
 curl -X POST http://localhost:8181/cxs/profiles/search \
---user karaf:karaf \
+--user "TENANT_ID:PRIVATE_KEY" \
 -H "Content-Type: application/json" \
 -d @- <<'EOF'
 {
diff --git a/manual/src/main/asciidoc/recipes.adoc b/manual/src/main/asciidoc/recipes.adoc
index 00dc7ee2c..a245375c4 100644
--- a/manual/src/main/asciidoc/recipes.adoc
+++ b/manual/src/main/asciidoc/recipes.adoc
@@ -18,6 +18,7 @@
 In this section of the documentation we provide quick recipes focused on helping you achieve a specific result with
 Apache Unomi.
 
+[[_enabling_debug_mode]]
 ==== Enabling debug mode
 
 Although the examples provided in this documentation are correct (they will work "as-is"), 
@@ -70,6 +71,11 @@ therefore to find the source of a schema validation issue it's best to start fro
 The simplest way to retrieve profile data for the current profile is to simply send a request to the /cxs/context.json
 endpoint. However you will need to send a body along with that request. Here's an example:
 
+[NOTE]
+====
+The `/cxs/context.json` endpoint automatically creates or loads profiles and sessions as needed. See <<_how_profile_tracking_works,How profile tracking works>> for complete details about the automatic profile and session creation process.
+====
+
 Here is an example that will retrieve all the session and profile properties, as well as the profile's segments and scores
 
 [source]
@@ -313,11 +319,11 @@ There could be two types of common errors while customizing the above requests:
 * The schema is invalid
 * The event is invalid
 
-While first submitting the schema during its creation, Apache Unomi will validate it is syntaxically correct (JSON) 
+While first submitting the schema during its creation, Apache Unomi will validate it is syntactically correct (JSON) 
 but will not perform any further validation. Since the schema will be processed for the first time when events are submitted, 
 errors might be noticeable at that time. 
 
-Those errors are usually self-explanatory, such as this one pointing to an incorrect lcoation for the "firstName" keyword:
+Those errors are usually self-explanatory, such as this one pointing to an incorrect location for the "firstName" keyword:
 [source]
 ----
 09:35:56.573 WARN [qtp1421852915-83] Unknown keyword firstName - you should define your own Meta Schema. If the keyword is irrelevant for validation, just use a NonValidationKeyword
@@ -449,7 +455,7 @@ on the server and potentially this could affect performance.
 
 ==== Getting / updating consents
 
-You can find information on how to retrieve or create/update consents in the <<Consent API>> section.
+You can find information on how to retrieve or create/update consents in the <<_consent_api,Consent API>> section.
 
 ==== How to send a login event to Unomi
 
@@ -589,7 +595,7 @@ Upon merge:
 ===== Decision Guide for Profile Merging
 
 [plantuml]
-....
+----
 @startuml
 title When to Use Profile Merges
 
@@ -623,7 +629,7 @@ endif
 MergeProfilesOnPropertyAction;
 stop
 @enduml
-....
+----
 
 ===== Troubleshooting Common Issues
 
diff --git a/manual/src/main/asciidoc/request-examples.adoc b/manual/src/main/asciidoc/request-examples.adoc
index a0b61b488..25d0774ed 100644
--- a/manual/src/main/asciidoc/request-examples.adoc
+++ b/manual/src/main/asciidoc/request-examples.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_request_examples]]
 === Request examples
 
 ==== Prerequisites
@@ -27,8 +28,7 @@ curl -X POST http://localhost:8181/cxs/tenants \
 --user karaf:karaf \
 -H "Content-Type: application/json" \
 -d '{
-    "itemId": "mytenant",
-    "scope": "system",
+    "requestedId": "mytenant",
     "properties": {
         "name": "My Company",
         "description": "My tenant description"
@@ -36,9 +36,33 @@ curl -X POST http://localhost:8181/cxs/tenants \
 }'
 ----
 
+The response will include the created tenant with automatically generated API keys:
+
+[source,json]
+----
+{
+    "itemId": "mytenant",
+    "name": "My Company",
+    "description": "My tenant description",
+    "apiKeys": [
+        {
+            "type": "PUBLIC",
+            "key": "public-key-abc123...",
+            "created": "2024-01-01T00:00:00Z"
+        },
+        {
+            "type": "PRIVATE",
+            "key": "private-key-xyz789...",
+            "created": "2024-01-01T00:00:00Z"
+        }
+    ]
+}
+----
+
 After creating the tenant, you will need to use these credentials in the examples:
 - Tenant ID: `mytenant`
-- Private API Key: Get this from the response of the tenant creation request
+- Private API Key: Extract the `key` value from the API key with `type: "PRIVATE"` in the response
+- Public API Key: Extract the `key` value from the API key with `type: "PUBLIC"` in the response
 
 ===== 2. Create a scope
 
@@ -165,6 +189,19 @@ This will retrieve a JavaScript script that contains a `cxs` object that contain
 profile, segments, scores as well as functions that makes it easier to perform further requests (such as collecting
 events using the cxs.collectEvents() function).
 
+[NOTE]
+====
+When you make a request to the `context.js` or `context.json` endpoints, Apache Unomi automatically:
+
+* Creates or loads a visitor profile (from cookie, parameter, or creates a new one)
+* Creates or loads a visitor session (if `sessionId` is provided)
+* Processes any events provided in the request (which automatically triggers rule execution)
+* Resolves personalization (if requested)
+* Sets a cookie with the profile ID in the response
+
+For detailed information about how profile tracking, session management, event processing, and rule execution work, see the <<_how_profile_tracking_works,How profile tracking works>> section.
+====
+
 ==== Retrieving a context as a JSON object.
 
 If you prefer to retrieve a pure JSON object, you can simply use a request formed like this:
@@ -174,6 +211,8 @@ If you prefer to retrieve a pure JSON object, you can simply use a request forme
 curl http://localhost:8181/cxs/context.json?sessionId=1234
 ----
 
+The same automatic profile and session creation behavior applies to `context.json` requests. See <<_how_profile_tracking_works,How profile tracking works>> for complete details.
+
 ==== Accessing profile properties in a context
 
 By default, in order to optimize the amount of data sent over the network, Apache Unomi will not send the content of
diff --git a/manual/src/main/asciidoc/samples/login-sample.adoc b/manual/src/main/asciidoc/samples/login-sample.adoc
index 60f9acf6b..ef04b18c8 100644
--- a/manual/src/main/asciidoc/samples/login-sample.adoc
+++ b/manual/src/main/asciidoc/samples/login-sample.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_login_sample]]
 === Login sample
 
 This samples is an example of what is involved in integrated a login with Apache Unomi.
diff --git a/manual/src/main/asciidoc/samples/samples.adoc b/manual/src/main/asciidoc/samples/samples.adoc
index fc4488567..45d0c3829 100644
--- a/manual/src/main/asciidoc/samples/samples.adoc
+++ b/manual/src/main/asciidoc/samples/samples.adoc
@@ -11,9 +11,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_samples]]
 === Samples
 
 Apache Unomi provides the following samples:
 
-* <<Twitter sample,Twitter integration>>
-* <<Login sample,Login integration>>
+* <<_twitter_sample,Twitter integration>>
+* <<_login_sample,Login integration>>
diff --git a/manual/src/main/asciidoc/samples/twitter-sample.adoc b/manual/src/main/asciidoc/samples/twitter-sample.adoc
index b522d12cb..918693fce 100644
--- a/manual/src/main/asciidoc/samples/twitter-sample.adoc
+++ b/manual/src/main/asciidoc/samples/twitter-sample.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_twitter_sample]]
 === Twitter sample
 
 ==== Overview
diff --git a/manual/src/main/asciidoc/security.adoc b/manual/src/main/asciidoc/security.adoc
index ebbc36446..02eb3bd83 100644
--- a/manual/src/main/asciidoc/security.adoc
+++ b/manual/src/main/asciidoc/security.adoc
@@ -12,7 +12,7 @@
 // limitations under the License.
 //
 
-=== Security Architecture
+==== Security Architecture
 
 [plantuml]
 ----
@@ -79,4 +79,4 @@ end note
 @enduml
 ----
 
-=== Overview 
\ No newline at end of file
+===== Overview 
\ No newline at end of file
diff --git a/manual/src/main/asciidoc/useful-unomi-urls.adoc b/manual/src/main/asciidoc/useful-unomi-urls.adoc
index 468793c26..49b054659 100644
--- a/manual/src/main/asciidoc/useful-unomi-urls.adoc
+++ b/manual/src/main/asciidoc/useful-unomi-urls.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_useful_apache_unomi_urls]]
 === Useful Apache Unomi URLs
 
 In this section we will list some useful URLs that can be used to quickly access parts of Apache Unomi that can help
diff --git a/manual/src/main/asciidoc/web-tracker.adoc b/manual/src/main/asciidoc/web-tracker.adoc
index e88718c7d..051036b86 100644
--- a/manual/src/main/asciidoc/web-tracker.adoc
+++ b/manual/src/main/asciidoc/web-tracker.adoc
@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
+[[_unomi_web_tracker_reference]]
 === Unomi Web Tracker reference
 
 In this section of the documentation, more details are provided about the web tracker provided by Unomi.
@@ -54,7 +55,7 @@ The first step is to declare a JSON schema for your custom event type. Here's an
 }
 ----
 
-The above example comes from a built-in event type that is already declared in Unomi but that illustrates the structure of a JSON schema. It is not however the objective of this section of the documentation to go into the details of how to declare a JSON schema, instead, we recommend you go to the <<_json_schemas_2,corresponding section>> of the documentation.
+The above example comes from a built-in event type that is already declared in Unomi but that illustrates the structure of a JSON schema. It is not however the objective of this section of the documentation to go into the details of how to declare a JSON schema, instead, we recommend you go to the <<_json_schemas,corresponding section>> of the documentation.
 
 ===== Sending event from tracker
 
diff --git a/manual/src/main/asciidoc/whats-new.adoc b/manual/src/main/asciidoc/whats-new.adoc
index bafd19357..febe1479a 100644
--- a/manual/src/main/asciidoc/whats-new.adoc
+++ b/manual/src/main/asciidoc/whats-new.adoc
@@ -25,7 +25,7 @@ The documentation of the client can be found here: https://www.elastic.co/docs/r
 
 ===  Elasticsearch 7 data migration
 
-A procedure to migrate your data from Elasticsearch 7 to Elasticsearch 9 can be found in the <<Migrate from Elasticsearch 7 to Elasticsearch 9>> section
+A procedure to migrate your data from Elasticsearch 7 to Elasticsearch 9 can be found in the <<_migrate_from_elasticsearch_7_to_elasticsearch_9,Migrate from Elasticsearch 7 to Elasticsearch 9>> section
 
 === Karaf upgrade
 
@@ -49,7 +49,7 @@ Users can choose between ElasticSearch and OpenSearch through various configurat
 2. Using Maven profiles during build
 3. Using Docker environment variables
 
-For detailed configuration instructions, see the <<Configuration,configuration section>>.
+For detailed configuration instructions, see the <<_configuration,configuration section>>.
 
 ===== Security Considerations
 
@@ -65,4 +65,4 @@ For users wanting to migrate from ElasticSearch to OpenSearch:
 - All existing features, including the flattened field type, are supported
 - Existing queries and aggregations work seamlessly with both backends
 
-For detailed migration instructions, refer to the <<Migrations,migration guide>>.
+For detailed migration instructions, refer to the <<_migrations,migration guide>>.
diff --git a/manual/src/main/asciidoc/writing-plugins.adoc b/manual/src/main/asciidoc/writing-plugins.adoc
index 2e0722401..b5f0f7a8b 100644
--- a/manual/src/main/asciidoc/writing-plugins.adoc
+++ b/manual/src/main/asciidoc/writing-plugins.adoc
@@ -248,10 +248,12 @@ A strategy to resolve how to merge properties when merging profile together.
 
 ==== PropertyType
 
-Definition for a profile or session property, specifying how possible values are constrained, if the value is
+Definition for a profile, session, or event property, specifying how possible values are constrained, if the value is
 multi-valued (a vector of values as opposed to a scalar value). `PropertyType`s can also be categorized using
 systemTags or file system structure, using sub-directories to organize definition files.
 
+For detailed information about property types, see <<_property_types,Property Types>>.
+
 ==== Rule
 
 `Rule`s are conditional sets of actions to be executed in response to incoming events. Triggering of rules is guarded
@@ -283,8 +285,8 @@ Definition for values that can be assigned to properties ("primitive" types).
 === Custom plugins
 
 Apache Unomi is a pluggeable server that may be extended in many ways. This document assumes you are familiar with the
-<<Data Model Overview,Apache Unomi Data Model>> . This document is mostly a reference document on the different things that may
-be used inside an extension. If you are looking for complete samples, please see the <<Samples,samples page>>.
+<<_data_model_overview,Apache Unomi Data Model>> . This document is mostly a reference document on the different things that may
+be used inside an extension. If you are looking for complete samples, please see the <<_samples,samples page>>.
 
 ==== Creating a plugin
 
@@ -347,7 +349,7 @@ When you deploy a custom bundle with a custom definition (see "Predefined xxx" c
 definition will automatically be deployed at your bundle start event *if it does not exist*.
 After that if you redeploy the same bundle, the definition will not be redeployed, but you can redeploy it manually
 using the command `unomi:deploy-definition &lt;bundleId&gt; &lt;fileName&gt;` If you need to modify an existing
-definition when deploying the module, see <<Migration patches>>.
+definition when deploying the module, see <<_migration_patches,Migration patches>>.
 
 ==== Predefined segments
 
@@ -1005,6 +1007,7 @@ my-custom-plugin/
      - For OpenSearch: `feature:install my-custom-plugin-opensearch`
    - Document dependencies and requirements clearly
 
+[[_custom_distribution_feature]]
 ==== Custom Distribution Feature
 
 For production deployments, you can create a custom distribution's feature file to automatically include your plugin features in the startup configuration. This approach ensures your plugin is automatically deployed when Apache Unomi starts.
@@ -1058,8 +1061,9 @@ For production deployments, you can create a custom distribution's feature file
 - **Production ready**: No manual feature installation required
 - **Version control**: Configuration can be versioned and managed with your deployment
 
-**Note**: For more detailed information about custom distributions, including environment-specific examples, see the <<Custom Distribution Feature,Configuration>> section of the documentation.
+**Note**: For more detailed information about custom distributions, including environment-specific examples, see the <<_custom_distribution_feature,Custom Distribution Feature>> section or the <<_configuration,Configuration>> section of the documentation.
 
++
 6. **Migration from Legacy Implementations**
    - **DO NOT** use legacy mappings for custom query builders
    - Rename existing query builders to follow new naming conventions