wip

Author: simbo1905

AGENTS.md

@@ -14,6 +14,26 @@
 - Never commit unverified mass changes—compile or test first.
 - Do not use Perl or sed for multi-line structural edits; rely on Python 3.2-friendly heredocs.
 
+## Markdown-Driven-Development (MDD)
+We practice **Markdown-Driven-Development** where documentation precedes implementation:
+
+1. **Create GitHub issue** with clear problem statement and goals
+2. **Update user documentation** (README.md) with new behavior/semantics
+3. **Update agentic documentation** (AGENTS.md) with implementation guidance
+4. **Update specialist documentation** (**/*.md, e.g., ARCHITECTURE.md) as needed
+5. **Create implementation plan** (PLAN_${issue_id}.md) documenting exact changes
+6. **Implement code changes** to match documented behavior
+7. **Update tests** to validate the documented behavior
+8. **Verify all documentation** remains accurate after implementation
+
+This ensures:
+- Users understand behavior changes before code is written
+- Developers have clear implementation guidance
+- Documentation stays synchronized with code
+- Breaking changes are clearly communicated
+
+When making changes, always update documentation files before modifying code.
+
 
 ## Testing & Logging Discipline
 
@@ -498,6 +518,16 @@ IMPORTANT: Never disable tests written for logic that we are yet to write we do
     * Virtual threads for concurrent processing
     * **Use try-with-resources for all AutoCloseable resources** (HttpClient, streams, etc.)
 
+## RFC 8927 Compliance Guidelines
+
+* **Do not introduce AJV/JSON Schema compatibility semantics**
+* **{} must always compile as an empty object schema** (no properties allowed per RFC 8927)
+* **If tests or legacy code expect {} to mean "accept anything", update them to expect failure**
+* **The validator emits an INFO-level log when {} is compiled** to help catch migration issues
+* **Empty schema {} is equivalent to**: `{ "properties": {}, "optionalProperties": {}, "additionalProperties": false }`
+
+When implementing JTD validation logic, ensure strict RFC 8927 compliance rather than maintaining compatibility with other JSON schema specifications.
+
 ## Package Structure
 
 * Use default (package-private) access as the standard. Do not use 'private' or 'public' by default.

README.md

@@ -295,6 +295,16 @@ This repo contains an incubating JTD validator that has the core JSON API as its
 
 A complete JSON Type Definition validator is included (module: json-java21-jtd).
 
+### Empty Schema `{}` Semantics
+
+In RFC 8927 (JSON Typedef), the empty schema `{}` means:
+- An object with **no properties allowed**.
+- Equivalent to `{ "properties": {}, "optionalProperties": {}, "additionalProperties": false }`.
+
+⚠️ Note: Some JSON Schema / AJV implementations treat `{}` as "accept anything".
+This library is RFC 8927–strict and will reject documents with any properties.
+A log message at INFO level is emitted when `{}` is compiled to highlight this difference.
+
 ```java
 import json.java21.jtd.Jtd;
 import jdk.sandbox.java.util.json.*;

json-java21-jtd/ARCHITECTURE.md

@@ -288,6 +288,17 @@ $(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-j
 - **Definitions**: Validate all definitions exist at compile time
 - **Type Checking**: Strict RFC 8927 compliance for all primitive types
 
+## Empty Schema Semantics
+
+**RFC 8927 Strict Compliance**: The empty schema `{}` has specific semantics that differ from other JSON schema specifications:
+
+- **RFC 8927 Meaning**: `{}` means an object with no properties allowed
+- **Equivalent to**: `{ "properties": {}, "optionalProperties": {}, "additionalProperties": false }`
+- **Valid Input**: Only `{}` (empty object)
+- **Invalid Input**: Any object with properties
+
+**Important Note**: Some JSON Schema and AJV implementations treat `{}` as "accept anything". This JTD validator is RFC 8927-strict and will reject documents with additional properties. An INFO-level log message is emitted when `{}` is compiled to highlight this semantic difference.
+
 ## RFC 8927 Compliance
 
 This implementation strictly follows RFC 8927:

json-java21-jtd/src/main/java/json/java21/jtd/Jtd.java

@@ -18,8 +18,7 @@ public class Jtd {
   /// Top-level definitions map for ref resolution
   private final Map<String, JtdSchema> definitions = new java.util.HashMap<>();
 
-  /// Raw definition values for context-aware ref resolution
-  private final Map<String, JsonValue> rawDefinitions = new java.util.HashMap<>();
+  // Removed: RFC 8927 strict mode - no context-aware compilation needed
 
   /// Stack frame for iterative validation with path and offset tracking
   record Frame(JtdSchema schema, JsonValue instance, String ptr, Crumbs crumbs, String discriminatorKey) {
@@ -285,11 +284,6 @@ void pushChildFrames(Frame frame, java.util.Deque<Frame> stack) {
 
   /// Compiles a JsonValue into a JtdSchema based on RFC 8927 rules
   JtdSchema compileSchema(JsonValue schema) {
-    return compileSchema(schema, false); // Default: not from ref resolution
-  }
-  
-  /// Compiles a JsonValue into a JtdSchema with context-aware handling of {}
-  JtdSchema compileSchema(JsonValue schema, boolean fromRef) {
     if (!(schema instanceof JsonObject obj)) {
       throw new IllegalArgumentException("Schema must be an object");
     }
@@ -308,19 +302,18 @@ JtdSchema compileSchema(JsonValue schema, boolean fromRef) {
       for (String key : defsObj.members().keySet()) {
         if (definitions.get(key) == null) {
           JsonValue rawDef = defsObj.members().get(key);
-          rawDefinitions.put(key, rawDef); // Store raw definition for context-aware ref resolution
-          // Compile definitions with fromRef=true for compatibility mode
-          JtdSchema compiled = compileSchema(rawDef, true);
+          // Compile definitions normally (RFC 8927 strict)
+          JtdSchema compiled = compileSchema(rawDef);
           definitions.put(key, compiled);
         }
       }
     }
 
-    return compileObjectSchema(obj, fromRef);
+    return compileObjectSchema(obj);
   }
 
-  /// Compiles an object schema according to RFC 8927 with context-aware handling
-  JtdSchema compileObjectSchema(JsonObject obj, boolean fromRef) {
+  /// Compiles an object schema according to RFC 8927 with strict semantics
+  JtdSchema compileObjectSchema(JsonObject obj) {
     // Check for mutually-exclusive schema forms
     List<String> forms = new ArrayList<>();
     Map<String, JsonValue> members = obj.members();
@@ -347,18 +340,15 @@ JtdSchema compileObjectSchema(JsonObject obj, boolean fromRef) {
     // Parse the specific schema form
     JtdSchema schema;
 
-    // Context-aware handling of {} - RFC vs compatibility mode
+    // RFC 8927 strict: {} always means "no properties allowed"
     if (forms.isEmpty() && obj.members().isEmpty()) {
-      if (fromRef) {
-        // Compatibility mode: {} from ref resolution behaves as EmptySchema (accept anything)
-        schema = new JtdSchema.EmptySchema();
-      } else {
-        // RFC mode: {} at root or direct context behaves as PropertiesSchema (no properties allowed)
-        schema = new JtdSchema.PropertiesSchema(Map.of(), Map.of(), false);
-      }
+      LOG.info(() -> "Empty schema {} encountered. "
+        + "Note: In some JSON validation specs this means 'accept anything', "
+        + "but per RFC 8927 it means an object with no properties allowed.");
+      return new JtdSchema.PropertiesSchema(Map.of(), Map.of(), false);
     } else if (forms.isEmpty()) {
       // Empty schema with no explicit form - default to EmptySchema for backwards compatibility
-      schema = new JtdSchema.EmptySchema();
+      return new JtdSchema.EmptySchema();
     } else {
       String form = forms.getFirst();
       schema = switch (form) {
@@ -503,10 +493,7 @@ JtdSchema compileDiscriminatorSchema(JsonObject obj) {
     return new JtdSchema.DiscriminatorSchema(discStr.value(), mapping);
   }
 
-  /// Gets raw definition value for context-aware ref resolution
-  JsonValue getRawDefinition(String ref) {
-    return rawDefinitions.get(ref);
-  }
+  // Removed: RFC 8927 strict mode - no context-aware ref resolution needed
 
   /// Extracts and stores top-level definitions for ref resolution
   private Map<String, JtdSchema> parsePropertySchemas(JsonObject propsObj) {

json-java21-jtd/src/test/java/json/java21/jtd/DocumentationAJvTests.java

@@ -233,42 +233,45 @@ public void testSelfReferencingSchema() throws Exception {
     LOG.fine(() -> "Self-referencing schema test - schema: " + schema + ", tree: " + tree);
   }
 
-  /// Empty form: any data
+  /// Empty form: RFC 8927 strict - {} means "no properties allowed"
   @Test
-  public void testEmptyForm() throws Exception {
+  public void testEmptyFormRfcStrict() throws Exception {
     JsonValue schema = Json.parse("{}");
 
-    // Test various data types
-    JsonValue stringData = Json.parse("\"hello\"");
-    JsonValue numberData = Json.parse("42");
-    JsonValue objectData = Json.parse("{\"key\": \"value\"}");
-    JsonValue arrayData = Json.parse("[1, 2, 3]");
-    JsonValue nullData = Json.parse("null");
-    JsonValue boolData = Json.parse("true");
-
-    assertThat(schema).isNotNull();
-    assertThat(stringData).isNotNull();
-    assertThat(numberData).isNotNull();
-    assertThat(objectData).isNotNull();
-    assertThat(arrayData).isNotNull();
-    assertThat(nullData).isNotNull();
-    assertThat(boolData).isNotNull();
-    LOG.fine(() -> "Empty form test - schema: " + schema + ", accepts any data");
+    // Test valid empty object
+    JsonValue emptyObject = Json.parse("{}");
+    Jtd validator = new Jtd();
+    Jtd.Result validResult = validator.validate(schema, emptyObject);
+    assertThat(validResult.isValid())
+      .as("Empty schema {} should accept empty object per RFC 8927")
+      .isTrue();
+
+    // Test invalid object with properties
+    JsonValue objectWithProps = Json.parse("{\"key\": \"value\"}");
+    Jtd.Result invalidResult = validator.validate(schema, objectWithProps);
+    assertThat(invalidResult.isValid())
+      .as("Empty schema {} should reject object with properties per RFC 8927")
+      .isFalse();
+    assertThat(invalidResult.errors())
+      .as("Should have validation error for additional property")
+      .isNotEmpty();
+
+    LOG.fine(() -> "Empty form RFC strict test - schema: " + schema + ", valid: empty object, invalid: object with properties");
   }
 
-  /// Counter-test: Empty form validation should pass for any data (no invalid data)
-  /// Same schema as testEmptyForm but tests that no data is invalid
+  /// Counter-test: Empty form validation should reject objects with properties per RFC 8927
+  /// Same schema as testEmptyFormRfcStrict but tests invalid data
   @Test
-  public void testEmptyFormInvalid() throws Exception {
+  public void testEmptyFormRejectsProperties() throws Exception {
     JsonValue schema = Json.parse("{}");
 
-    // Test that empty schema accepts any data - should pass for "invalid" data
-    JsonValue anyData = Json.parse("{\"anything\": \"goes\"}");
+    // Test that empty schema rejects object with properties per RFC 8927
+    JsonValue dataWithProps = Json.parse("{\"anything\": \"goes\"}");
     Jtd validator = new Jtd();
-    Jtd.Result result = validator.validate(schema, anyData);
-    assertThat(result.isValid()).isTrue();
-    assertThat(result.errors()).isEmpty();
-    LOG.fine(() -> "Empty form invalid test - schema: " + schema + ", any data should pass: " + anyData);
+    Jtd.Result result = validator.validate(schema, dataWithProps);
+    assertThat(result.isValid()).isFalse();
+    assertThat(result.errors()).isNotEmpty();
+    LOG.fine(() -> "Empty form rejects properties test - schema: " + schema + ", data with properties should fail: " + dataWithProps);
   }
 
   /// Type form: numeric types