easy_talk 3.2.0 → 3.3.1

data/docs/json_schema_compliance.md

@@ -8,9 +8,9 @@ This document defines the strategy for testing and improving `EasyTalk`'s compli
 
 ### Infrastructure
 
-*   **Submodule**: Located at `spec/fixtures/json_schema_test_suite`.
-*   **Converter**: `spec/support/json_schema_converter.rb` dynamically converts raw JSON Schema definitions into `EasyTalk::Model` classes at runtime.
-*   **Runner**: `spec/integration/json_schema_compliance_spec.rb` iterates over the test suite files, generates models, and asserts valid/invalid behavior.
+- **Submodule**: Located at `spec/fixtures/json_schema_test_suite`.
+- **Converter**: `spec/support/json_schema_converter.rb` dynamically converts raw JSON Schema definitions into `EasyTalk::Model` classes at runtime.
+- **Runner**: `spec/integration/json_schema_compliance_spec.rb` iterates over the test suite files, generates models, and asserts valid/invalid behavior.
 
 ## Running the Tests
 
@@ -22,34 +22,148 @@ To run the compliance suite:
 bundle exec rspec --tag json_schema_compliance spec/integration/json_schema_compliance_spec.rb
 ```
 
-## Compliance Strategy
+## Schema Wrapping Strategy
 
-The goal is to incrementally improve compliance by enabling more tests and fixing the underlying issues in `EasyTalk`.
+Since `EasyTalk` models are always objects, the JSON Schema test suite's root-level primitive tests (e.g., `{"type": "integer"}` with data `5`) require adaptation.
 
-### 1. Identify Gaps
-The current test runner skips many tests (marked as `pending` or explicit `skip`).
-*   **Root Primitives**: `EasyTalk` models are Objects. Tests for root integers/strings are skipped.
-*   **Strict Naming**: Tests with property names that are invalid Ruby identifiers (e.g., `foo-bar`, `123`, `constructor`) are currently skipped.
-*   **Missing Keywords**: Keywords like `patternProperties`, `const`, and `oneOf` (in specific contexts) may fail.
+### How It Works
 
-### 2. Workflow for Improvements
-1.  **Select a Feature**: Pick a specific file (e.g., `properties.json`, `required.json`) or a skipped section.
-2.  **Un-skip Tests**: Remove the `skip` logic in `spec/integration/json_schema_compliance_spec.rb` for that feature.
-3.  **Run & Analyze**: Run the specific test file.
-    ```bash
-    bundle exec rspec --tag json_schema_compliance
-    ```
-4.  **Implement Fix**: Modify `EasyTalk` internals (e.g., `keywords.rb`, `schema_definition.rb`) to support the feature.
-5.  **Sanitize Inputs**: Update `JsonSchemaConverter` if the test case requires adaptation (e.g., mapping a JSON key to a safe Ruby method name via `as:`) without changing the underlying validation logic.
+The `JsonSchemaConverter` uses a **wrapper property strategy**:
 
-### 3. Known Critical Issues
-*   **Reserved Words**: Properties like `method`, `class`, `constructor` conflict with Ruby. Fix requires a robust proxy or sanitization layer in `EasyTalk::Model`.
-*   **Boolean Schemas**: `properties: { foo: false }` is valid JSON Schema (property forbidden) but not currently supported by `EasyTalk`.
-*   **Strict Property Validation**: `EasyTalk` raises errors for invalid property names at definition time. Compliance requires allowing arbitrary property keys (perhaps via `validates_with` logic instead of metaprogramming methods).
+1. **Detection**: `needs_wrapping?` checks if the schema is non-object (no `type: object` or `properties` key)
+2. **Wrapping**: Non-object schemas become a `value` property on a wrapper object
+3. **Data transformation**: Primitive test data is wrapped as `{"value": data}`
+
+**Example transformation:**
+
+```
+Original JSON Schema test:
+  Schema: {"type": "integer", "minimum": 1}
+  Data: 5
+  Valid: true
+
+Transformed for EasyTalk:
+  Schema: {
+    "type": "object",
+    "properties": { "value": {"type": "integer", "minimum": 1} },
+    "required": ["value"]
+  }
+  Data: {"value": 5}
+  Valid: true
+```
+
+This preserves validation semantics while fitting EasyTalk's object-based model.
+
+## Current Test Results
+
+As of the latest run:
+
+| Metric | Count |
+|--------|-------|
+| Total examples | 916 |
+| Passing | ~193 |
+| Failing | 165 |
+| Pending (known unsupported) | 558 |
+
+### Known Unsupported Features
+
+The following test files are skipped entirely via `KNOWN_FAILURES`:
+
+| File | Reason |
+|------|--------|
+| `not.json` | `not` keyword not supported |
+| `anyOf.json` | `anyOf` validation not supported |
+| `allOf.json` | `allOf` validation not supported |
+| `oneOf.json` | `oneOf` validation not supported |
+| `refRemote.json` | Remote `$ref` not supported |
+| `dependencies.json` | Dependencies not supported |
+| `definitions.json` | `$defs`/definitions not supported |
+| `if-then-else.json` | Conditional logic not supported |
+| `patternProperties.json` | Pattern properties not supported |
+| `properties.json` | Complex property interactions not supported |
+| `propertyNames.json` | Property names validation not supported |
+| `ref.json` | Complex `$ref` not supported |
+| `required.json` | Complex required checks not supported |
+| `additionalItems.json` | Additional items not supported |
+| `additionalProperties.json` | Additional properties validation not supported |
+| `boolean_schema.json` | Boolean schemas (`true`/`false` as schema) not supported |
+| `const.json` | `const` keyword not supported |
+| `default.json` | Default keyword behavior not supported |
+| `enum.json` | Enum validation not fully supported |
+| `infinite-loop-detection.json` | Infinite loop detection not supported |
+| `maxProperties.json` | Max properties not supported |
+| `minProperties.json` | Min properties not supported |
+
+## Compliance Gaps
+
+The 165 failing tests reveal real validation gaps in EasyTalk:
+
+### 1. Type Coercion (Intentional Behavior)
+
+EasyTalk uses ActiveModel's numericality validation which coerces strings to numbers:
+
+```ruby
+user = User.new(age: "30")  # String
+user.valid?  # => true (coerced to integer 30)
+```
+
+Per JSON Schema, `"30"` should be invalid for `type: integer`. This is documented as **intentional behavior** for Rails compatibility. A `strict_types` configuration option is planned (see [#137](https://github.com/sergiobayona/easy_talk/issues/137)).
+
+### 2. Format Validation Scope
+
+JSON Schema specifies that format validations should only apply to strings and ignore other types. EasyTalk currently validates format on the assigned value regardless of type.
+
+### 3. Empty String Presence
+
+EasyTalk uses ActiveModel's presence validation for required fields, which rejects empty strings. JSON Schema considers `""` a valid string.
+
+### 4. Array Type Validation
+
+Array element types are not strictly validated at runtime.
+
+### 5. Null Type
+
+The `null` type is not fully implemented as a standalone type.
+
+### 6. uniqueItems
+
+Array uniqueness constraint is not enforced during validation.
+
+## Workflow for Improvements
+
+1. **Select a Feature**: Pick a specific file from `KNOWN_FAILURES` or analyze failing tests.
+2. **Enable Tests**: Remove the file from `KNOWN_FAILURES` in the spec.
+3. **Run & Analyze**:
+   ```bash
+   bundle exec rspec --tag json_schema_compliance spec/integration/json_schema_compliance_spec.rb
+   ```
+4. **Implement Fix**: Modify EasyTalk internals to support the feature.
+5. **Update Converter**: If needed, update `JsonSchemaConverter` for test adaptation.
+
+## Critical Implementation Notes
+
+### Reserved Words
+
+Properties like `method`, `class`, `constructor` conflict with Ruby. The converter sanitizes these via `sanitize_property_name` and uses the `as:` option to preserve the original JSON key.
+
+### Boolean Schemas
+
+`properties: { foo: false }` is valid JSON Schema (property forbidden) but not currently supported.
+
+### Strict Property Validation
+
+EasyTalk raises `InvalidPropertyNameError` for invalid property names at definition time. Full compliance would require allowing arbitrary property keys.
 
 ## Contributing
 
 When adding support for a new JSON Schema keyword:
-1.  Check if a test file exists in `spec/fixtures/json_schema_test_suite/tests/draft7/`.
-2.  Add the filename to the `FOCUS_FILES` list in `spec/integration/json_schema_compliance_spec.rb`.
-3.  Implement the feature and verify pass.
+
+1. Check if a test file exists in `spec/fixtures/json_schema_test_suite/tests/draft7/`.
+2. Remove the filename from `KNOWN_FAILURES` in `spec/integration/json_schema_compliance_spec.rb`.
+3. Run the tests and analyze failures.
+4. Implement the feature in EasyTalk.
+5. Update this document with any new findings.
+
+## Related Issues
+
+- [#137](https://github.com/sergiobayona/easy_talk/issues/137) - Add `strict_types` configuration option