Utilizing JSONSchema For Parameter Validation

[its-hammer-time]

Summary

Poking through the code, it looks like your parameter validation logic is fairly custom and doesn't hook in with the JSONSchema library you're using; line in the body validation. Taking a look at both the OpenAPI 3.0.0 and 3.1.0 specs, it looks like all parameters follow the same structure of having some custom fields (e.g. in, style, required, etc.), but for the actual format of the parameter they both have a schema section which in 3.0.0 is the custom OpenAPI Schema object, but in 3.1.0 that's native JSONSchema. So my question is:

What are your thoughts on using the JSONSchema library for format validation and only keeping the OpenAPI specific pieces like style, required, etc.?

I'm working on wiring up libopenapi-validator in my own service and something I need to do is understand what "type" of error is being raised. For body issues this is fairly straight forward as the JSONSchema error that you raise with your error has a Kind on it that tells me what the issue was. However, for parameter issues, since you're not using the JSONSchema library those errors aren't there so I've been doing regex checking on your error strings which is obviously a brittle solution.

I'm curious to hear what your thoughts are on this? 🤔 I thought about working on getting a PR out, but I was hoping to get your insights before spending time on using JSONSchema validation for the parameters. Is that something you tried to do and there's a reason you're not using it there? Is it just a lack of bandwidth and it's on the roadmap? etc.

[its-hammer-time]

Hey team, any insight here? Just looking for some confirmation that this change would be approved before we spend time with the implementation. From what I've seen the overall structure is the following

ValidationError -> []SchemaValidationError -> jsonschema.ValidationError

• ValidationError - The "summarized" error that this library is raising with a human friendly message
• SchemaValidationError - A custom error from this library to wrap the JSONSchema error
• jsonschema.ValidationError - The error you received from JSONSchema

From what I see, there are three types of errors:

1. Go errors - Can't ready body, nil pointer, etc.
2. OpenAPI errors - Missing path, missing response body, missing mime-type, etc.
3. Schema errors - Something doesn't conform to the spec

My thinking is to have Go and OpenAPI errors raised as a ValidationError then have all "schema" errors be raised as an underlying SchemaValidationError. That way there's a consistent experience for clients so those cases that aren't caught by JSONSchema will be raised in the same spot. For example, the Parameter allowEmptyValues wouldn't be covered by JSONSchema.

---

I'd also like to add the Location to all of the schema validation errors. Note that you do already have a Location field, but that's the location to where the error occurred int he spec, not where the error occurred in the request or response. For example, here's a debug output for a Path Parameter exception. You can see that the only place we can see the id path parameter failed is the human friendly error message that's being raised. I'm currently pulling this out with a regex check, but that's really brittle.

In this scenario it'd be easy to assume the issue came from the id parameter since it's the only one, but what happens if the URL takes 2+ path parameters?

[daveshanley]

Hey, no team yet - just very kind volunteers.

I made some changes to unify the SchemaValidationFailure for v0.5.0 based on your ask.

Format assertions are already supported. To use parameter validation with format assertions, you need to enable format validation when creating the validator:

  import (
      "github.com/pb33f/libopenapi"
      "github.com/pb33f/libopenapi-validator/parameters"
      "github.com/pb33f/libopenapi-validator/config"
  )

  // Parse your OpenAPI document
  doc, err := libopenapi.NewDocument(specBytes)
  if err != nil {
      // handle error
  }

  // Build the V3 model
  v3Model, errs := doc.BuildV3Model()
  if len(errs) > 0 {
      // handle errors
  }

  // Create validator WITH format assertions enabled
  validator := parameters.NewParameterValidator(&v3Model.Model, config.WithFormatAssertions())

  // Create validator WITHOUT format assertions (default behavior)
  validator := parameters.NewParameterValidator(&v3Model.Model)

Configuration Options

The config.WithFormatAssertions()option enables JSONSchema format validation for common formats:

• email - Validates email addresses
• date - Validates RFC3339 date format (YYYY-MM-DD)
• date-time - Validates RFC3339 date-time format
• uuid - Validates UUID format
• uri - Validates URI format
• hostname - Validates hostname format
• And other JSONSchema draft formats

##Validating Parameters

  import "net/http"

  // Create your HTTP request
  request, _ := http.NewRequest("GET", "/api/users?email=invalid-email", nil)

  // Validate query parameters
  valid, errors := validator.ValidateQueryParams(request)

  // Validate header parameters
  valid, errors := validator.ValidateHeaderParams(request)

  // Validate path parameters
  valid, errors := validator.ValidatePathParams(request)

  // Validate cookie parameters
  valid, errors := validator.ValidateCookieParams(request)

New Unified Error Structure

The updated parameter validation provides a consistent error structure that matches body validation errors:

Error Hierarchy

ValidationError
└── SchemaValidationErrors []SchemaValidationFailure
└── OriginalError *jsonschema.ValidationError

example on how to use it.

  if len(errors) > 0 {
      validationError := errors[0]

      // Get human-readable summary
      fmt.Printf("Error: %s\n", validationError.Message)
      fmt.Printf("Reason: %s\n", validationError.Reason)

      // Access structured schema validation details
      if len(validationError.SchemaValidationErrors) > 0 {
          schemaError := validationError.SchemaValidationErrors[0]

          fmt.Printf("Schema error: %s\n", schemaError.Reason)
          fmt.Printf("Failed at: %s\n", schemaError.Location)
          fmt.Printf("Invalid value: %s\n", schemaError.ReferenceObject)
          fmt.Printf("Expected schema: %s\n", schemaError.ReferenceSchema)

          // Access original JSONSchema error if needed
          if schemaError.OriginalError != nil {
              // Work with raw jsonschema.ValidationError
          }
      }
  }

  Format Validation Example

  // OpenAPI spec with format validation
  spec := `
  openapi: 3.1.0
  paths:
    /users:
      get:
        parameters:
          - name: email
            in: query
            required: true
            schema:
              type: string
              format: email
  `

  // Request with invalid email
  request, _ := http.NewRequest("GET", "/users?email=invalid-email", nil)

  // Validate (with format assertions enabled)
  valid, errors := validator.ValidateQueryParams(request)

  // Handle structured error
  if !valid && len(errors) > 0 {
      error := errors[0]
      // error.Message: "Query parameter 'email' failed to validate"

      schemaError := error.SchemaValidationErrors[0]
      // schemaError.Reason: "'invalid-email' is not valid email: missing @"
      // schemaError.Location: "/format"
      // schemaError.ReferenceObject: "invalid-email"
  }

Multiple Parameter Scenarios

When multiple parameters fail validation, you get precise error context for each:

  // Request: /users/123/posts?limit=abc&email=invalid
  // Multiple validation failures

  valid, errors := validator.ValidateQueryParams(request)

  for _, err := range errors {
      fmt.Printf("Parameter validation failed:\n")
      fmt.Printf("  Summary: %s\n", err.Message)

      for _, schemaErr := range err.SchemaValidationErrors {
          fmt.Printf("  Schema failure: %s\n", schemaErr.Reason)
          fmt.Printf("  Location: %s\n", schemaErr.Location)
          fmt.Printf("  Failed value: %s\n", schemaErr.ReferenceObject)
      }
  }

[daveshanley]

I have added a ParameterName to ValidationError so you will have programmatic access to it, without having to parse anything

[daveshanley]

ValidationError now contains ParameterName.

available in v0.5.0