From 8d31c2ad44abd824a42001c3252bbffd13c338bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Francisco=20Javier=20Cavero=20L=C3=B3pez?=
 <javiercavlop@gmail.com>
Date: Thu, 29 Jan 2026 10:40:35 +0100
Subject: [PATCH] docs: updating README.md

---
 README.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2223c01..2086b38 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ graph TD
     Router -->|engine_id=random-search| RS[Random Search Engine]
     
     MZ -->|Solve via Gecode| Solution
-    RS -->|Solve via Evolution| Solution
+    RS -->|Solve via Random Heuristic| Solution
     
     Solution --> Gateway
     Gateway -->|HTTP 200| User
@@ -50,6 +50,26 @@ graph TD
         - **Schema Explorer**: Interactive JSON schema viewer with search and navigation
         - **Light/Dark Theme**: System-aware theme with persistence
 
+## 📐 Schemas & Specification
+
+OpenBinding validates incoming requests against two schema layers:
+
+1. **General schema** (engine-agnostic):
+    - JSON Schema (structural validation): `schemas/general/schema.json`
+    - Specification / semantics (human-readable): `schemas/general/schema.specification.md`
+
+    The specification document explains the intent and semantics behind the JSON Schema, including:
+    - The instance model (tasks, candidates, providers, features)
+    - Workflow modeling (`composition` as structured tree or DAG)
+    - QoS aggregation and normalization (`aggregation_policies`)
+    - Constraints and objectives, plus invariants that require a second validation pass
+
+2. **Specialization schemas** (engine-specific constraints):
+    - `schemas/specializations/minizinc-csp.schema.json`
+    - `schemas/specializations/random-search.schema.json`
+
+Example payloads that follow these schemas live in `examples/`.
+
 ## 🚀 Getting Started
 
 ### Prerequisites