Skip to content

Conversation

@mjbonifacio
Copy link
Owner

What Changed

Adds full OpenAPI KeywordLocation paths and ReferenceSchema context to all parameter validation errors (path, query, header, cookie parameters). Uses the centralized JSON Pointer helpers from PR #2.

Why

Before this change, parameter validation errors had incomplete context:

  • Missing ReferenceSchema field (couldn't see the schema that was violated)
  • Missing or incomplete KeywordLocation (hard to locate the exact schema rule)
  • Inconsistent patterns across different parameter types

Now all parameter errors include:

  • Full OpenAPI path in KeywordLocation: e.g., /paths/~1users~1{id}/get/parameters/id/schema/minimum
  • Rendered schema in ReferenceSchema: The actual schema definition as JSON string
  • Consistent structure: All 4 parameter types follow the same pattern

This makes debugging much easier - you can see exactly which schema rule was violated and where it's defined in your OpenAPI spec.

Pattern Applied

Each parameter validation function now:

  1. Renders the schema once (at the start of validation)
  2. Passes renderedSchema to error functions (avoid re-rendering on each error)
  3. Uses helper functions for KeywordLocation construction

Example (Path parameter validation):

// Render schema once for all errors
renderedSchema, _ := json.Marshal(param.Schema.Schema().RenderInline())

// Pass to error function
err := errors.IncorrectPathParamNumber(
    pathTemplate, operation, param.Name, 
    renderedSchema,  // ← New: for ReferenceSchema field
    value,
)

SchemaValidationFailure Changes

Path Parameter Validation

Error Type Before After Changes
All path param errors (35 functions) ⚠️ Missing ReferenceSchema ✅ Has ReferenceSchema + full KeywordLocation Added schema context and OpenAPI paths using helpers

Query Parameter Validation

Error Type Before After Changes
All query param errors ⚠️ Missing ReferenceSchema ✅ Has ReferenceSchema + full KeywordLocation Added schema context and OpenAPI paths using helpers
Missing required query param ❌ No SchemaValidationFailure ✅ Has SchemaValidationFailure Added - this IS a schema constraint violation (required: true)

Header Parameter Validation

Error Type Before After Changes
All header param errors ⚠️ Missing ReferenceSchema ✅ Has ReferenceSchema + full KeywordLocation Added schema context and OpenAPI paths using helpers

Cookie Parameter Validation

Error Type Before After Changes
All cookie param errors ⚠️ Missing ReferenceSchema ✅ Has ReferenceSchema + full KeywordLocation Added schema context and OpenAPI paths using helpers

Dependency Note

⚠️ Depends on PR #1 and PR #2 - Review those first for context on SchemaValidationFailure usage and helper functions.

Commits (4)

  1. Path parameters: render schema once, pass to error functions
  2. Query parameters: add full OpenAPI context + missing required param fix
  3. Header parameters: add full OpenAPI context
  4. Cookie parameters: add full OpenAPI context

Michael Bonifacio added 4 commits November 15, 2025 11:43
…r ReferenceSchema

- Render parameter schema once in path_parameters.go instead of in each error function
- Pass renderedSchema to all 8 path parameter error functions (bool, enum, integer, number, array variants)
- Update Context field to use raw base.Schema (programmatic access)
- Update ReferenceSchema field to use rendered JSON string (API consumers)
- Use full OpenAPI JSON Pointer paths for KeywordLocation (e.g., /paths/~1users~1{id}/parameters/id/schema/type)
- Serialize full schema objects for ReferenceSchema instead of just type strings
- Update resolveNumber and resolveInteger helpers to accept and pass renderedSchema

Note: This approach (Context=raw schema, ReferenceSchema=rendered string) will be reviewed later for consistency across the codebase
Changes:
- Remove 'Build full OpenAPI path for KeywordLocation' comments
- Remove inline comments from previous commits
- Add renderedSchema parameter to QueryParameterMissing
- Set ReferenceSchema field in QueryParameterMissing SchemaValidationFailure
- Render schema for missing required parameters before creating error
- Update tests to pass renderedSchema parameter
Adds full OpenAPI context to all 7 header parameter error functions:
- HeaderParameterMissing
- HeaderParameterCannotBeDecoded (now includes SchemaValidationFailure)
- IncorrectHeaderParamEnum
- InvalidHeaderParamInteger
- InvalidHeaderParamNumber
- IncorrectHeaderParamBool
- IncorrectHeaderParamArrayBoolean
- IncorrectHeaderParamArrayNumber

All errors now include:
- KeywordLocation: Full JSON Pointer from OpenAPI root (e.g., /paths/{path}/{method}/parameters/{name}/schema/type)
- ReferenceSchema: Rendered schema as JSON string
- Context: Raw base.Schema object
- Proper FieldName and InstancePath

Updated ValidateHeaderArray to accept and pass path/operation/schema context.
Updated all test cases to pass new required parameters.
Adds full OpenAPI context to all 6 cookie parameter error functions:
- InvalidCookieParamInteger
- InvalidCookieParamNumber
- IncorrectCookieParamBool
- IncorrectCookieParamEnum
- IncorrectCookieParamArrayBoolean
- IncorrectCookieParamArrayNumber

All errors now include:
- KeywordLocation: Full JSON Pointer from OpenAPI root (e.g., /paths/{path}/{method}/parameters/{name}/schema/type)
- ReferenceSchema: Rendered schema as JSON string
- Context: Raw base.Schema object
- Proper FieldName and InstancePath

Updated ValidateCookieArray to accept and pass path/operation/schema context.
Updated all test cases to pass new required parameters.

This completes consistent SchemaValidationFailure population across all parameter types (path, query, header, cookie).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants