Pre-validation Error Cleanup: Distinguish pre-validation errors from schema constraint violations

[mjbonifacio]

What Changed

Establishes a clear distinction between pre-validation errors (where input cannot be parsed/compiled to reach schema validation) and schema constraint violations (where input violates a defined schema rule) across 6 validation types.

Why

Improves error clarity for library consumers by only including SchemaValidationFailure when there's an actual schema to reference. This makes it easier to:

• Understand whether an error is due to malformed input or schema violations
• Programmatically distinguish between error categories
• Provide better error messages to end users

SchemaValidationFailure Changes

Schema/Document Validation

Error Type	Before	After	Reason
Schema compilation failure	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	Cannot reference a schema that failed to compile
Document compilation failure	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	Cannot reference a schema that failed to compile
Schema constraint violations	✅ Has SchemaValidationFailure	✅ Has SchemaValidationFailure	Actual schema rule violation - unchanged

Parameter Validation

Error Type	Before	After	Reason
Parameter schema compilation failure	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	Cannot reference a schema that failed to compile
Parameter constraint violations	✅ Has SchemaValidationFailure	✅ Has SchemaValidationFailure	Actual schema rule violation - unchanged
Added KeywordLocation	❌ Missing	✅ Populated	Points to schema keyword that failed (e.g., "/minLength")

Request Body Validation

Error Type	Before	After	Reason
JSON decode failure	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	Cannot validate malformed JSON
Empty request body (required)	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	No body to validate against schema
Schema compilation failure	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	Cannot reference a schema that failed to compile
Schema constraint violations	✅ Has SchemaValidationFailure	✅ Has SchemaValidationFailure	Actual schema rule violation - unchanged

Response Body Validation

Error Type	Before	After	Reason
JSON/YAML decode failure	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	Cannot validate malformed content
Empty response body (required)	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	No body to validate against schema
Schema compilation failure	❌ Had SchemaValidationFailure	✅ No SchemaValidationFailure	Cannot reference a schema that failed to compile
Schema constraint violations	✅ Has SchemaValidationFailure	✅ Has SchemaValidationFailure	Actual schema rule violation - unchanged

Other Changes

• Removed AbsoluteKeywordLocation field: This field was never populated because RenderInline() resolves all $ref references before validation, so the JSON Schema validator never encounters $ref pointers. Removing unused field reduces struct size and complexity.

⚠️ Potential Rollback Point

The AbsoluteKeywordLocation removal is based on observed behavior (field always empty due to schema inlining). If there are use cases where this field should be populated or if the library has plans to support it in the future, this change could be rolled back to commit f0fc5b5 (just before the removal).

Question for maintainer: Is there a use case for AbsoluteKeywordLocation that we're missing, or is it safe to remove this unused field?

Commits (6)

1. Remove SchemaValidationFailure from schema pre-validation errors
2. Remove SchemaValidationFailure from document compilation errors
3. Parameters: add KeywordLocation when formatting JSON schema errors, remove SchemaValidationFailure when compilation fails
4. Remove AbsoluteKeywordLocation field - never populated due to schema inlining
5. Request body validation: remove SchemaValidationFailure from pre-validation errors
6. Response body validation: remove SchemaValidationFailure from pre-validation errors