docs(oasf): taxonomy and schema validator updates

docs/oasf/contributing.md

@@ -40,20 +40,25 @@ contribute to the development of OASF Schemas and the framework itself.
 - **Attribute**:
   An attribute is the more generic name for both fields and entities in OASF.
   A field is a scalar attribute while an entity is a complex attribute.
-- **Category:** A Category organizes classes that represent a particular domain.
+- **Category:** A Category organizes classes that represent a particular domain. Categories are marked by adding `"category": true` to a class JSON file and can be created at any level of the taxonomy tree.
 
 ## How to Add to the Schema
 
 ### Adding or Modifying a `class`
 
 1. Determine where in the taxonomy of the class family you would want to add the
    new `class`.
-2. Create a new file → `<class_name.json>` inside the family and category
-   specific subdirectory in the
-   [/schema](https://github.com/agntcy/oasf/tree/main/schema) folder.
+2. Create a new file called `<class_name.json>` inside the appropriate subdirectory
+   in the [/schema](https://github.com/agntcy/oasf/tree/main/schema) folder.
+   The directory structure reflects the taxonomy hierarchy (e.g., classes that
+   extend a category should be placed in that category's subdirectory).
    Template available
    [here](https://github.com/agntcy/oasf/blob/main/schema/templates/class_name.json).
 3. Define the `class` itself.
+   - If this class represents a category (organizational structure), add
+     `"category": true` to the JSON. Categories can be created at any level of
+     the taxonomy tree by extending other categories.
+   - Set the `uid` field to a unique identifier within the category hierarchy.
 4. In case of a `module` class, make sure to overwrite the `data` attribute with
    a new object containing all the module-specific attributes →
    [Defining an `object`](#defining-an-object).
@@ -387,17 +392,19 @@ The extension's directory structure is the same as the top level schema
 directory, and it may contain the following files and subdirectories, depending
 on what type of extension is desired:
 
-| Name                | Description                                |
-| ------------------- | ------------------------------------------ |
-| `main_skills.json`  | Create it to define new skill categories.  |
-| `main_domains.json` | Create it to define new domain categories. |
-| `main_modules.json` | Create it to define new module categories. |
-| `dictionary.json`   | Create it to define new attributes.        |
-| `skills`            | Create it to define new skill classes.     |
-| `domains`           | Create it to define new domain classes.    |
-| `modules`           | Create it to define new module classes.    |
-| `objects`           | Create it to define new objects.           |
-| `profiles`          | Create it to define new profiles.          |
+| Name              | Description                                                          |
+| ----------------- | -------------------------------------------------------------------- |
+| `dictionary.json`  | Create it to define new attributes.                                 |
+| `skills`          | Create it to define new skill classes. Categories are created by adding `"category": true` to a skill class JSON file. |
+| `domains`         | Create it to define new domain classes. Categories are created by adding `"category": true` to a domain class JSON file. |
+| `modules`         | Create it to define new module classes. Categories are created by adding `"category": true` to a module class JSON file. |
+| `objects`         | Create it to define new objects.                                     |
+| `profiles`        | Create it to define new profiles.                                   |
+
+!!! note
+    Categories are no longer defined in separate category files. Instead,
+    mark any class as a category by adding `"category": true` to its JSON file.
+    Categories can be nested at any level by having one category extend another.
 
 ## Reporting Issues
 
@@ -458,7 +465,7 @@ Here is what you can do:
   _[Reporting Issues](#reporting-issues)_ section, providing feedback to the
   issue's author on what might be missing.
 - Review and update the existing content of our
-  [docs](https://docs.agntcy.org/oasf/open-agentic-schema-framework) with
+  [docs](./open-agentic-schema-framework.md) with
   up-to-date instructions and code samples.
 - Review existing pull requests, and testing patches against real existing
   applications that use `OASF`.

docs/oasf/validation-comparison.md

@@ -21,8 +21,8 @@ This table compares validation outcomes between the OASF API validator and JSON
 | 2. Version Incompatibility (Initial Dev) | `schema_version: "0.1.0"` when server is `0.8.0`                      | ERROR (`version_incompatible_initial_development`)       | PASS        | JSON Schema validates format only, not SemVer rules <a href="#note-1"><sup>1</sup></a>                             |
 | 3. Version Incompatibility (Prerelease)  | `schema_version: "0.8.0-alpha"` when server is `0.8.0`                | ERROR (`version_incompatible_prerelease`)                | PASS        | JSON Schema validates format only, not prerelease compatibility <a href="#note-1"><sup>1</sup></a>                 |
 | 4. Version Earlier (Compatible)          | `schema_version: "0.7.0"` when server is `0.8.0`                      | WARNING (`version_earlier`)                              | PASS        | JSON Schema validates format only, not version comparison <a href="#note-1"><sup>1</sup></a>                       |
-| 5. Regex Pattern Mismatch                | `previous_record_cid: "invalid"` (doesn't match CID regex)            | WARNING (`attribute_value_regex_not_matched`)            | PASS        | JSON Schema may export regex but validation is lenient; API treats as warning                                      |
-| 6. Regex Pattern Mismatch (Super Type)   | String doesn't match super type regex                                 | WARNING (`attribute_value_super_type_regex_not_matched`) | PASS        | Same as above for super types                                                                                      |
+| 5. Regex Pattern Mismatch                | `previous_record_cid: "invalid"` (doesn't match CID regex)            | WARNING (`attribute_value_regex_not_matched`)            | FAIL        | JSON Schema emits `pattern` from dictionary type regex; API treats as warning but JSON Schema rejects              |
+| 6. Regex Pattern Mismatch (Super Type)   | String doesn't match super type regex                                 | WARNING (`attribute_value_super_type_regex_not_matched`) | FAIL        | JSON Schema emits `pattern` from super type regex; API treats as warning but JSON Schema rejects                   |
 | 7. Using Base Class                      | `skills: [{"name": "base_skill"}]` or `skills: [{"id": 0}]`           | ERROR (`base_class_used`)                                | FAIL        | Both catch base classes (base_skill, base_domain, base_module); JSON Schema `oneOf` doesn't include parent classes |
 | 8. Using Deprecated Class                | Using a deprecated skill/domain/module                                | WARNING (`class_deprecated`)                             | PASS        | JSON Schema doesn't track deprecation                                                                              |
 | 9. Using Deprecated Attribute            | Using a deprecated attribute                                          | WARNING (`attribute_deprecated`)                         | PASS        | JSON Schema doesn't track deprecation                                                                              |
@@ -39,7 +39,7 @@ This table compares validation outcomes between the OASF API validator and JSON
 | 20. Unknown Enum Value                   | Enum value not in allowed list                                        | ERROR (`attribute_enum_value_unknown`)                   | FAIL        | JSON Schema uses `enum` constraint                                                                                 |
 | 21. Unknown Enum Array Value             | Enum array value not in allowed list                                  | ERROR (`attribute_enum_array_value_unknown`)             | FAIL        | JSON Schema validates array items                                                                                  |
 | 22. Value Outside Range                  | Number outside type's range                                           | ERROR (`attribute_value_exceeds_range`)                  | FAIL        | JSON Schema uses `minimum`/`maximum`                                                                               |
-| 23. Value Exceeds Max Length             | String exceeds type's max length                                      | ERROR (`attribute_value_exceeds_max_len`)                | FAIL        | JSON Schema uses `maxLength`                                                                                       |
+| 23. Value Exceeds Max Length             | String exceeds type's max length                                      | ERROR (`attribute_value_exceeds_max_len`)                | FAIL        | JSON Schema uses `maxLength` (including inherited `max_len` from super types)                                      |
 | 24. Value Not in Type Values             | Value not in type's allowed values list                               | ERROR (`attribute_value_not_in_type_values`)             | FAIL        | JSON Schema uses `enum` constraint                                                                                 |
 | 25. Unknown Class ID                     | `id: 99999` doesn't exist                                             | ERROR (`id_unknown`)                                     | FAIL        | JSON Schema uses `oneOf` with `const` values                                                                       |
 | 26. Unknown Class Name                   | `name: "nonexistent"` doesn't exist                                   | ERROR (`name_unknown`)                                   | FAIL        | JSON Schema uses `oneOf` with `const` values                                                                       |
@@ -65,13 +65,16 @@ This table compares validation outcomes between the OASF API validator and JSON
 2. Enum array sibling validation (missing, incorrect)
 3. Unknown profile (for classes)
 
+### API WARNING, JSON Schema FAILS (JSON Schema Stricter)
+
+1. Regex pattern mismatches (JSON Schema emits `pattern` from dictionary types and super types)
+
 ### API WARNING, JSON Schema PASSES (Non-blocking Issues)
 
 1. Version earlier (compatible)
-2. Regex pattern mismatches
-3. All deprecation warnings (class, attribute, object, enum values)
-4. Enum sibling mismatches
-5. Missing recommended attributes
+2. All deprecation warnings (class, attribute, object, enum values)
+3. Enum sibling mismatches
+4. Missing recommended attributes
 
 ### Both FAIL (Both Catch the Issue)
 
@@ -93,15 +96,15 @@ This table compares validation outcomes between the OASF API validator and JSON
 ## Key Insights
 
 1. JSON Schema is comprehensive for structural and value validation
-2. Main gaps in JSON Schema:
+2. JSON Schema is stricter than the API validator for regex pattern mismatches: the API treats these as warnings (non-blocking), while JSON Schema `pattern` constraints cause hard failures
+3. Main gaps in JSON Schema:
 
     - Semantic version compatibility (only validates format)
     - Enum array sibling validation
     - Deprecation tracking
-    - Regex validation (treated as warnings, not errors)
     - Profile existence (for classes)
 
-3. Both validators catch most structural and type validation issues, including:
+4. Both validators catch most structural and type validation issues, including:
 
     - Base classes (now errors in API validator, matching JSON Schema behavior)
     - Array duplicates (both use duplicate detection)