Skip to content

Commit bb9ae15

Browse files
simbo1905simbo1905
committed
json schema
1 parent 84d41ca commit bb9ae15

File tree

7 files changed

+1195
-2
lines changed

7 files changed

+1195
-2
lines changed

‎AGENTS.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Quick Start Commands
6+
7+
### Building the Project
8+
```bash
9+
# Full build
10+
mvn clean compile
11+
mvn package
12+
13+
# Build specific module
14+
mvn clean compile -pl json-java21
15+
mvn package -pl json-java21
16+
17+
# Build with test skipping
18+
mvn clean compile -DskipTests
19+
```
20+
21+
### Running Tests
22+
```bash
23+
# Run all tests
24+
mvn test
25+
26+
# Run tests with clean output (recommended)
27+
./mvn-test-no-boilerplate.sh
28+
29+
# Run specific test class
30+
./mvn-test-no-boilerplate.sh -Dtest=JsonParserTests
31+
./mvn-test-no-boilerplate.sh -Dtest=JsonTypedUntypedTests
32+
33+
# Run specific test method
34+
./mvn-test-no-boilerplate.sh -Dtest=JsonParserTests#testParseEmptyObject
35+
36+
# Run tests in specific module
37+
./mvn-test-no-boilerplate.sh -pl json-java21-api-tracker -Dtest=ApiTrackerTest
38+
```
39+
40+
### JSON Compatibility Suite
41+
```bash
42+
# Build and run compatibility report
43+
./mvnw clean compile generate-test-resources -pl json-compatibility-suite
44+
./mvnw exec:java -pl json-compatibility-suite
45+
46+
# Run JSON output (dogfoods the API)
47+
./mvnw exec:java -pl json-compatibility-suite -Dexec.args="--json"
48+
```
49+
50+
### Debug Logging
51+
```bash
52+
# Enable debug logging for specific test
53+
./mvn-test-no-boilerplate.sh -Dtest=JsonParserTests -Djava.util.logging.ConsoleHandler.level=FINER
54+
```
55+
56+
## Architecture Overview
57+
58+
### Module Structure
59+
- **`json-java21`**: Core JSON API implementation (main library)
60+
- **`json-java21-api-tracker`**: API evolution tracking utilities
61+
- **`json-compatibility-suite`**: JSON Test Suite compatibility validation
62+
63+
### Core Components
64+
65+
#### Public API (jdk.sandbox.java.util.json)
66+
- **`Json`** - Static utility class for parsing/formatting/conversion
67+
- **`JsonValue`** - Sealed root interface for all JSON types
68+
- **`JsonObject`** - JSON objects (key-value pairs)
69+
- **`JsonArray`** - JSON arrays
70+
- **`JsonString`** - JSON strings
71+
- **`JsonNumber`** - JSON numbers
72+
- **`JsonBoolean`** - JSON booleans
73+
- **`JsonNull`** - JSON null
74+
75+
#### Internal Implementation (jdk.sandbox.internal.util.json)
76+
- **`JsonParser`** - Recursive descent JSON parser
77+
- **`Json*Impl`** - Immutable implementations of JSON types
78+
- **`Utils`** - Internal utilities and factory methods
79+
80+
### Design Patterns
81+
- **Algebraic Data Types**: Sealed interfaces with exhaustive pattern matching
82+
- **Immutable Value Objects**: All types are immutable and thread-safe
83+
- **Lazy Evaluation**: Strings/numbers store offsets until accessed
84+
- **Factory Pattern**: Static factory methods for construction
85+
- **Bridge Pattern**: Clean API/implementation separation
86+
87+
## Key Development Practices
88+
89+
### Testing Approach
90+
- **JUnit 5** with AssertJ for fluent assertions
91+
- **Test Organization**:
92+
- `JsonParserTests` - Parser-specific tests
93+
- `JsonTypedUntypedTests` - Conversion tests
94+
- `JsonRecordMappingTests` - Record mapping tests
95+
- `ReadmeDemoTests` - Documentation example validation
96+
97+
### Code Style
98+
- **JEP 467 Documentation**: Use `///` triple-slash comments
99+
- **Immutable Design**: All public types are immutable
100+
- **Pattern Matching**: Use switch expressions with sealed types
101+
- **Null Safety**: Use `Objects.requireNonNull()` for public APIs
102+
103+
### Performance Considerations
104+
- **Lazy String/Number Creation**: Values computed on demand
105+
- **Singleton Patterns**: Single instances for true/false/null
106+
- **Defensive Copies**: Immutable collections prevent external modification
107+
- **Efficient Parsing**: Character array processing with minimal allocations
108+
109+
## Common Workflows
110+
111+
### Adding New JSON Type Support
112+
1. Add interface extending `JsonValue`
113+
2. Add implementation in `jdk.sandbox.internal.util.json`
114+
3. Update `Json.fromUntyped()` and `Json.toUntyped()`
115+
4. Add parser support in `JsonParser`
116+
5. Add comprehensive tests
117+
118+
### Debugging Parser Issues
119+
1. Enable `FINER` logging: `-Djava.util.logging.ConsoleHandler.level=FINER`
120+
2. Use `./mvn-test-no-boilerplate.sh` for clean output
121+
3. Focus on specific test: `-Dtest=JsonParserTests#testMethod`
122+
4. Check JSON Test Suite compatibility with compatibility suite
123+
124+
### API Compatibility Testing
125+
1. Run compatibility suite: `./mvnw exec:java -pl json-compatibility-suite`
126+
2. Check for regressions in JSON parsing
127+
3. Validate against official JSON Test Suite
128+
129+
## Module-Specific Details
130+
131+
### json-java21
132+
- **Main library** containing the core JSON API
133+
- **Maven coordinates**: `io.github.simbo1905.json:json-java21:0.1-SNAPSHOT`
134+
- **JDK requirement**: Java 21+
135+
136+
### json-compatibility-suite
137+
- **Downloads** JSON Test Suite from GitHub automatically
138+
- **Reports** 99.3% conformance with JSON standards
139+
- **Identifies** security vulnerabilities (StackOverflowError with deep nesting)
140+
- **Usage**: Educational/testing, not production-ready
141+
142+
### json-java21-api-tracker
143+
- **Tracks** API evolution and compatibility
144+
- **Uses** Java 24 preview features (`--enable-preview`)
145+
- **Purpose**: Monitor upstream OpenJDK changes
146+
147+
## Security Notes
148+
- **Stack exhaustion attacks**: Deep nesting can cause StackOverflowError
149+
- **API contract violations**: Malicious inputs may trigger undeclared exceptions
150+
- **Status**: Experimental/unstable API - not for production use
151+
- **Vulnerabilities**: Inherited from upstream OpenJDK sandbox implementation

‎json-java21-api-tracker/pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
<name>API Tracker</name>
1717

1818
<properties>
19-
<maven.compiler.release>24</maven.compiler.release>
19+
<maven.compiler.release>21</maven.compiler.release>
2020
</properties>
2121

2222
<dependencies>
@@ -54,4 +54,4 @@
5454
</plugin>
5555
</plugins>
5656
</build>
57-
</project>
57+
</project>

‎json-java21-schema/README.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# JSON Schema Validator
2+
3+
Stack-based JSON Schema validator using sealed interface pattern with inner record types.
4+
5+
## API Design
6+
7+
Single public interface with all schema types as inner records:
8+
9+
```java
10+
package io.github.simbo1905.json.schema;
11+
12+
import jdk.sandbox.java.util.json.*;
13+
14+
public sealed interface JsonSchema permits JsonSchema.Nothing {
15+
16+
// Prevents external implementations
17+
enum Nothing implements JsonSchema {
18+
INSTANCE;
19+
}
20+
21+
// Factory method to create schema from JSON
22+
static JsonSchema compile(JsonValue schemaJson) {
23+
// Parses JSON Schema document into immutable record hierarchy
24+
// Throws IllegalArgumentException if schema is invalid
25+
}
26+
27+
// Validation method
28+
default ValidationResult validate(JsonValue json) {
29+
// Stack-based validation using inner schema records
30+
}
31+
32+
// Schema type records
33+
record ObjectSchema(
34+
Map<String, JsonSchema> properties,
35+
Set<String> required,
36+
JsonSchema additionalProperties,
37+
Integer minProperties,
38+
Integer maxProperties
39+
) implements JsonSchema {}
40+
41+
record ArraySchema(
42+
JsonSchema items,
43+
Integer minItems,
44+
Integer maxItems,
45+
Boolean uniqueItems
46+
) implements JsonSchema {}
47+
48+
record StringSchema(
49+
Integer minLength,
50+
Integer maxLength,
51+
Pattern pattern,
52+
Set<String> enumValues
53+
) implements JsonSchema {}
54+
55+
record NumberSchema(
56+
BigDecimal minimum,
57+
BigDecimal maximum,
58+
BigDecimal multipleOf,
59+
Boolean exclusiveMinimum,
60+
Boolean exclusiveMaximum
61+
) implements JsonSchema {}
62+
63+
record BooleanSchema() implements JsonSchema {}
64+
record NullSchema() implements JsonSchema {}
65+
record AnySchema() implements JsonSchema {}
66+
67+
record RefSchema(String ref) implements JsonSchema {}
68+
69+
record AllOfSchema(List<JsonSchema> schemas) implements JsonSchema {}
70+
record AnyOfSchema(List<JsonSchema> schemas) implements JsonSchema {}
71+
record OneOfSchema(List<JsonSchema> schemas) implements JsonSchema {}
72+
record NotSchema(JsonSchema schema) implements JsonSchema {}
73+
74+
// Validation result types
75+
record ValidationResult(boolean valid, List<ValidationError> errors) {
76+
public static ValidationResult valid() {
77+
return new ValidationResult(true, List.of());
78+
}
79+
public static ValidationResult invalid(List<ValidationError> errors) {
80+
return new ValidationResult(false, errors);
81+
}
82+
}
83+
84+
record ValidationError(String path, String message) {}
85+
}
86+
```
87+
88+
## Usage
89+
90+
```java
91+
import jdk.sandbox.java.util.json.*;
92+
import io.github.simbo1905.json.schema.JsonSchema;
93+
94+
// Compile schema once (thread-safe, reusable)
95+
String schemaDoc = """
96+
{
97+
"type": "object",
98+
"properties": {
99+
"name": {"type": "string"},
100+
"age": {"type": "number", "minimum": 0}
101+
},
102+
"required": ["name"]
103+
}
104+
""";
105+
106+
JsonSchema schema = JsonSchema.compile(Json.parse(schemaDoc));
107+
108+
// Validate JSON documents
109+
String jsonDoc = """
110+
{"name": "Alice", "age": 30}
111+
""";
112+
113+
JsonSchema.ValidationResult result = schema.validate(Json.parse(jsonDoc));
114+
115+
if (!result.valid()) {
116+
for (var error : result.errors()) {
117+
System.out.println(error.path() + ": " + error.message());
118+
}
119+
}
120+
```

‎json-java21-schema/pom.xml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
5+
http://maven.apache.org/xsd/maven-4.0.0.xsd">
6+
<modelVersion>4.0.0</modelVersion>
7+
8+
<parent>
9+
<groupId>io.github.simbo1905.json</groupId>
10+
<artifactId>json-java21-parent</artifactId>
11+
<version>0.1-SNAPSHOT</version>
12+
</parent>
13+
14+
<artifactId>json-java21-schema</artifactId>
15+
<packaging>jar</packaging>
16+
<name>JSON Schema Validator</name>
17+
18+
<properties>
19+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
20+
<maven.compiler.release>21</maven.compiler.release>
21+
</properties>
22+
23+
<dependencies>
24+
<dependency>
25+
<groupId>io.github.simbo1905.json</groupId>
26+
<artifactId>json-java21</artifactId>
27+
<version>${project.version}</version>
28+
</dependency>
29+
<dependency>
30+
<groupId>org.junit.jupiter</groupId>
31+
<artifactId>junit-jupiter-api</artifactId>
32+
<scope>test</scope>
33+
</dependency>
34+
<dependency>
35+
<groupId>org.junit.jupiter</groupId>
36+
<artifactId>junit-jupiter-engine</artifactId>
37+
<scope>test</scope>
38+
</dependency>
39+
<dependency>
40+
<groupId>org.assertj</groupId>
41+
<artifactId>assertj-core</artifactId>
42+
<scope>test</scope>
43+
</dependency>
44+
</dependencies>
45+
</project>

0 commit comments

Comments
 (0)