implement x-www-form-urlencoded validation

Potentially closes #180

Author: ySnoopyDogy

config/config.go

@@ -21,17 +21,18 @@ type RegexCache interface {
 //
 // Generally fluent With... style functions are used to establish the desired behavior.
 type ValidationOptions struct {
-	RegexEngine            jsonschema.RegexpEngine
-	RegexCache             RegexCache // Enable compiled regex caching
-	FormatAssertions       bool
-	ContentAssertions      bool
-	SecurityValidation     bool
-	OpenAPIMode            bool // Enable OpenAPI-specific vocabulary validation
-	AllowScalarCoercion    bool // Enable string->boolean/number coercion
-	Formats                map[string]func(v any) error
-	SchemaCache            cache.SchemaCache // Optional cache for compiled schemas
-	Logger                 *slog.Logger      // Logger for debug/error output (nil = silent)
-	AllowXMLBodyValidation bool              // Allows to convert XML to JSON when validating a request/response body.
+	RegexEngine                   jsonschema.RegexpEngine
+	RegexCache                    RegexCache // Enable compiled regex caching
+	FormatAssertions              bool
+	ContentAssertions             bool
+	SecurityValidation            bool
+	OpenAPIMode                   bool // Enable OpenAPI-specific vocabulary validation
+	AllowScalarCoercion           bool // Enable string->boolean/number coercion
+	Formats                       map[string]func(v any) error
+	SchemaCache                   cache.SchemaCache // Optional cache for compiled schemas
+	Logger                        *slog.Logger      // Logger for debug/error output (nil = silent)
+	AllowXMLBodyValidation        bool              // Allows to convert XML to JSON for validating a request/response body.
+	AllowURLEncodedBodyValidation bool              // Allows to convert URL Encoded to JSON for validating a request/response body.
 
 	// strict mode options - detect undeclared properties even when additionalProperties: true
 	StrictMode                bool     // Enable strict property validation
@@ -77,6 +78,7 @@ func WithExistingOpts(options *ValidationOptions) Option {
 			o.SchemaCache = options.SchemaCache
 			o.Logger = options.Logger
 			o.AllowXMLBodyValidation = options.AllowXMLBodyValidation
+			o.AllowURLEncodedBodyValidation = options.AllowURLEncodedBodyValidation
 			o.StrictMode = options.StrictMode
 			o.StrictIgnorePaths = options.StrictIgnorePaths
 			o.StrictIgnoredHeaders = options.StrictIgnoredHeaders
@@ -171,6 +173,14 @@ func WithXmlBodyValidation() Option {
 	}
 }
 
+// WithURLEncodedBodyValidation enables converting an URL Encoded body to a JSON when validating the schema from a request and response body
+// The default option is set to false
+func WithURLEncodedBodyValidation() Option {
+	return func(o *ValidationOptions) {
+		o.AllowURLEncodedBodyValidation = true
+	}
+}
+
 // WithSchemaCache sets a custom cache implementation or disables caching if nil.
 // Pass nil to disable schema caching and skip cache warming during validator initialization.
 // The default cache is a thread-safe sync.Map wrapper.

config/config_test.go

@@ -19,9 +19,10 @@ func TestNewValidationOptions_Defaults(t *testing.T) {
 	assert.False(t, opts.FormatAssertions)
 	assert.False(t, opts.ContentAssertions)
 	assert.True(t, opts.SecurityValidation)
-	assert.True(t, opts.OpenAPIMode)             // Default is true
-	assert.False(t, opts.AllowScalarCoercion)    // Default is false
-	assert.False(t, opts.AllowXMLBodyValidation) // Default is false
+	assert.True(t, opts.OpenAPIMode)                    // Default is true
+	assert.False(t, opts.AllowScalarCoercion)           // Default is false
+	assert.False(t, opts.AllowXMLBodyValidation)        // Default is false
+	assert.False(t, opts.AllowURLEncodedBodyValidation) // Default is false
 	assert.Nil(t, opts.RegexEngine)
 	assert.Nil(t, opts.RegexCache)
 }
@@ -97,12 +98,13 @@ func TestWithExistingOpts(t *testing.T) {
 	// Create original options with all settings enabled
 	var testEngine jsonschema.RegexpEngine = nil
 	original := &ValidationOptions{
-		RegexEngine:            testEngine,
-		RegexCache:             &sync.Map{},
-		FormatAssertions:       true,
-		AllowXMLBodyValidation: true,
-		ContentAssertions:      true,
-		SecurityValidation:     false,
+		RegexEngine:                   testEngine,
+		RegexCache:                    &sync.Map{},
+		FormatAssertions:              true,
+		AllowXMLBodyValidation:        true,
+		AllowURLEncodedBodyValidation: true,
+		ContentAssertions:             true,
+		SecurityValidation:            false,
 	}
 
 	// Create new options using existing options
@@ -111,6 +113,7 @@ func TestWithExistingOpts(t *testing.T) {
 	assert.Nil(t, opts.RegexEngine) // Both should be nil
 	assert.NotNil(t, opts.RegexCache)
 	assert.Equal(t, original.AllowXMLBodyValidation, opts.AllowXMLBodyValidation)
+	assert.Equal(t, original.AllowURLEncodedBodyValidation, opts.AllowURLEncodedBodyValidation)
 	assert.Equal(t, original.FormatAssertions, opts.FormatAssertions)
 	assert.Equal(t, original.ContentAssertions, opts.ContentAssertions)
 	assert.Equal(t, original.SecurityValidation, opts.SecurityValidation)
@@ -189,6 +192,14 @@ func TestWithExistingOpts_PartialOverride(t *testing.T) {
 	assert.False(t, opts.SecurityValidation) // From original
 }
 
+func TestWithUrlEncodedBodyValidation(t *testing.T) {
+	opts := NewValidationOptions(
+		WithURLEncodedBodyValidation(),
+	)
+
+	assert.True(t, opts.AllowURLEncodedBodyValidation)
+}
+
 func TestComplexScenario(t *testing.T) {
 	// Test a complex real-world scenario
 	var mockEngine jsonschema.RegexpEngine = nil

errors/parameters_howtofix.go

@@ -15,14 +15,17 @@ const (
 	HowToFixInvalidXml                              string = "Ensure xml is well-formed and matches schema structure"
 	HowToFixXmlPrefix                               string = "Make sure to prepend the correct prefix '%s' to the declared fields"
 	HowToFixXmlNamespace                            string = "Make sure to declare the 'xmlns:%s' with the correct namespace URI"
+	HowToFixFormDataReservedCharacters              string = "Make sure to correcly encode specials characters to percent encoding, or set allowReserved to true"
 	HowToFixInvalidSchema                           string = "Ensure that the object being submitted, matches the schema correctly"
+	HowToFixInvalidTypeEncoding                     string = "Ensure that the object being submitted matches the property encoding Content-Type"
 	HowToFixParamInvalidSpaceDelimitedObjectExplode string = "When using 'explode' with space delimited parameters, " +
 		"they should be separated by spaces. For example: '%s'"
 	HowToFixParamInvalidPipeDelimitedObjectExplode string = "When using 'explode' with pipe delimited parameters, " +
 		"they should be separated by pipes '|'. For example: '%s'"
 	HowToFixParamInvalidDeepObjectMultipleValues string = "There can only be a single value per property name, " +
 		"deepObject parameters should contain the property key in square brackets next to the parameter name. For example: '%s'"
 	HowToFixInvalidJSON           string = "The JSON submitted is invalid, please check the syntax"
+	HowToFixInvalidUrlEncoded     string = "Ensure URL Encoded submitted is well-formed and matches schema structure"
 	HowToFixDecodingError         string = "The object can't be decoded, so make sure it's being encoded correctly according to the spec."
 	HowToFixInvalidContentType    string = "The content type is invalid, Use one of the %d supported types for this operation: %s"
 	HowToFixInvalidResponseCode   string = "The service is responding with a code that is not defined in the spec, fix the service or add the code to the specification"

errors/urlencoded_errors.go

@@ -0,0 +1,66 @@
+package errors
+
+import (
+	"fmt"
+
+	"github.com/pb33f/libopenapi-validator/helpers"
+	"github.com/pb33f/libopenapi/datamodel/high/base"
+)
+
+func InvalidURLEncodedParsing(reason, referenceObject string) *ValidationError {
+	return &ValidationError{
+		ValidationType:    helpers.URLEncodedValidation,
+		ValidationSubType: helpers.Schema,
+		Message:           "Unable to parse form-urlencoded body",
+		Reason:            fmt.Sprintf("failed to parse form-urlencoded: %s", reason),
+		SchemaValidationErrors: []*SchemaValidationFailure{{
+			Reason:          reason,
+			Location:        "url encoded parsing",
+			ReferenceSchema: "",
+			ReferenceObject: referenceObject,
+		}},
+		HowToFix: HowToFixInvalidUrlEncoded,
+	}
+}
+
+func InvalidTypeEncoding(schema *base.Schema, name, contentType string) *ValidationError {
+	line := 1
+	col := 0
+	if low := schema.GoLow(); low != nil && low.Type.KeyNode != nil {
+		line = low.Type.KeyNode.Line
+		col = low.Type.KeyNode.Column
+	}
+
+	return &ValidationError{
+		ValidationType:    helpers.URLEncodedValidation,
+		ValidationSubType: helpers.InvalidTypeEncoding,
+		Message:           fmt.Sprintf("The value '%s' could not be parsed to the defined encoding", name),
+		Reason:            fmt.Sprintf("The value '%s' is encoded as '%s' in the schema, however the value could not be parsed", name, contentType),
+		SpecLine:          line,
+		SpecCol:           col,
+		Context:           schema,
+		HowToFix:          HowToFixInvalidTypeEncoding,
+	}
+}
+
+func ReservedURLEncodedValue(schema *base.Schema, name, value string) *ValidationError {
+	line := 1
+	col := 0
+	if schema != nil {
+		if low := schema.GoLow(); low != nil && low.Type.KeyNode != nil {
+			line = low.Type.KeyNode.Line
+			col = low.Type.KeyNode.Column
+		}
+	}
+
+	return &ValidationError{
+		ValidationType:    helpers.URLEncodedValidation,
+		ValidationSubType: helpers.ReservedValues,
+		Message:           fmt.Sprintf("Form value '%s' contains reserved characters", name),
+		Reason:            fmt.Sprintf("The form value '%s' contains reserved characters but allowReserved is false. Value: '%s'", name, value),
+		SpecLine:          line,
+		SpecCol:           col,
+		Context:           schema,
+		HowToFix:          HowToFixFormDataReservedCharacters,
+	}
+}

errors/urlencoded_errors_test.go

@@ -0,0 +1,57 @@
+package errors
+
+import (
+	"testing"
+
+	"github.com/pb33f/libopenapi"
+	"github.com/pb33f/libopenapi-validator/helpers"
+	"github.com/pb33f/libopenapi/datamodel/high/base"
+	"github.com/stretchr/testify/assert"
+)
+
+func getURLEncodingTestSchema() *base.Schema {
+	spec := `openapi: 3.0.0
+paths:
+  /pet:
+    get:
+      responses:
+        '200':
+          content:
+            application/x-www-form-urlencoded:
+              encoding:
+                animal:
+                  contentType: application/json
+              schema:
+                type: object
+                properties:
+                  animal:
+                    type: object`
+
+	doc, _ := libopenapi.NewDocument([]byte(spec))
+	v3Doc, _ := doc.BuildV3Model()
+
+	return v3Doc.Model.Paths.PathItems.GetOrZero("/pet").Get.Responses.Codes.GetOrZero("200").
+		Content.GetOrZero("application/x-www-form-urlencoded").Schema.Schema()
+}
+
+func TestInvalidURLEncodedParsing(t *testing.T) {
+	err := InvalidURLEncodedParsing("no data sent", "invalid-formdata")
+
+	assert.NotNil(t, (*err))
+	assert.Equal(t, (*err).SchemaValidationErrors[0].Location, "url encoded parsing")
+	assert.Equal(t, helpers.Schema, (*err).ValidationSubType)
+}
+
+func TestInvalidTypeEncoding(t *testing.T) {
+	err := InvalidTypeEncoding(getURLEncodingTestSchema(), "animal", helpers.JSONContentType)
+
+	assert.NotNil(t, (*err))
+	assert.Equal(t, helpers.InvalidTypeEncoding, (*err).ValidationSubType)
+}
+
+func TestReservedURLEncodedValue(t *testing.T) {
+	err := ReservedURLEncodedValue(getURLEncodingTestSchema(), "animal", "!")
+
+	assert.NotNil(t, (*err))
+	assert.Equal(t, helpers.ReservedValues, (*err).ValidationSubType)
+}

errors/xml_errors.go

@@ -88,7 +88,7 @@ func InvalidNamespace(schema *base.Schema, namespace, expectedNamespace, prefix
 	}
 }
 
-func InvalidXmlParsing(reason, referenceObject string) *ValidationError {
+func InvalidXMLParsing(reason, referenceObject string) *ValidationError {
 	return &ValidationError{
 		ValidationType:    helpers.XmlValidation,
 		ValidationSubType: helpers.Schema,

errors/xml_errors_test.go

@@ -69,7 +69,7 @@ func TestInvalidNamespaceError(t *testing.T) {
 }
 
 func TestInvalidParsing(t *testing.T) {
-	err := InvalidXmlParsing("no data sent", "invalid-xml")
+	err := InvalidXMLParsing("no data sent", "invalid-xml")
 
 	assert.NotNil(t, (*err))
 	assert.Equal(t, (*err).SchemaValidationErrors[0].Location, "xml parsing")

helpers/constants.go

@@ -14,6 +14,9 @@ const (
 	XmlValidation             = "xmlValidation"
 	XmlValidationPrefix       = "prefix"
 	XmlValidationNamespace    = "namespace"
+	URLEncodedValidation      = "urlEncodedValidation"
+	InvalidTypeEncoding       = "invalidTypeEncoding"
+	ReservedValues            = "reservedValues"
 	Schema                    = "schema"
 	ResponseBodyValidation    = "response"
 	RequestBodyContentType    = "contentType"
@@ -51,6 +54,7 @@ const (
 	Form                       = "form"
 	Query                      = "query"
 	JSONContentType            = "application/json"
+	URLEncodedContentType      = "application/x-www-form-urlencoded"
 	JSONType                   = "json"
 	ContentTypeHeader          = "Content-Type"
 	AuthorizationHeader        = "Authorization"

requests/validate_body.go

@@ -78,10 +78,17 @@ func (v *requestBodyValidator) ValidateRequestBodyWithPathItem(request *http.Req
 	// extract schema from media type
 	schema := mediaType.Schema.Schema()
 
-	if !strings.Contains(strings.ToLower(contentType), helpers.JSONType) {
-		// we currently only support JSON and XML validation for request bodies
-		// this will capture *everything* that contains some form of 'json' in the content type
-		if !v.options.AllowXMLBodyValidation || !schema_validation.IsXMLContentType(contentType) {
+	isJson := strings.Contains(strings.ToLower(contentType), helpers.JSONType)
+
+	// we currently only support JSON, XML and URLEncoded validation for request bodies
+	if !isJson {
+		isXml := schema_validation.IsXMLContentType(contentType)
+		isUrlEncoded := schema_validation.IsURLEncodedContentType(contentType)
+
+		xmlValid := isXml && v.options.AllowXMLBodyValidation
+		urlEncodedValid := isUrlEncoded && v.options.AllowURLEncodedBodyValidation
+
+		if !xmlValid && !urlEncodedValid {
 			return true, nil
 		}
 
@@ -90,15 +97,22 @@ func (v *requestBodyValidator) ValidateRequestBodyWithPathItem(request *http.Req
 			_ = request.Body.Close()
 
 			stringedBody := string(requestBody)
-			jsonBody, prevalidationErrors := schema_validation.TransformXMLToSchemaJSON(stringedBody, schema)
+			var jsonBody any
+			var prevalidationErrors []*errors.ValidationError
+
+			switch {
+			case xmlValid:
+				jsonBody, prevalidationErrors = schema_validation.TransformXMLToSchemaJSON(stringedBody, schema)
+			case urlEncodedValid:
+				jsonBody, prevalidationErrors = schema_validation.TransformURLEncodedToSchemaJSON(stringedBody, schema, mediaType.Encoding)
+			}
+
 			if len(prevalidationErrors) > 0 {
 				return false, prevalidationErrors
 			}
 
-			transformedBytes, err := json.Marshal(jsonBody)
-			if err != nil {
-				return false, []*errors.ValidationError{errors.InvalidXmlParsing(err.Error(), stringedBody)}
-			}
+			// If prevalidationErrors has no items, jsonBody is a valid JSON structure
+			transformedBytes, _ := json.Marshal(jsonBody)
 
 			request.Body = io.NopCloser(bytes.NewBuffer(transformedBytes))
 		}

requests/validate_body_test.go

@@ -1617,6 +1617,51 @@ paths:
 	assert.Equal(t, errors[0].Message, "xml example is malformed")
 }
 
+func TestValidateBody_URLEncodedRequest(t *testing.T) {
+	spec := `openapi: 3.1.0
+paths:
+  /burgers/createBurger:
+    post:
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                patties:
+                  type: integer`
+
+	doc, _ := libopenapi.NewDocument([]byte(spec))
+
+	m, _ := doc.BuildV3Model()
+	v := NewRequestBodyValidator(&m.Model, config.WithURLEncodedBodyValidation())
+
+	body := "name=cheeseburger&patties=23"
+
+	request, _ := http.NewRequest(http.MethodPost, "https://things.com/burgers/createBurger",
+		bytes.NewBuffer([]byte(body)))
+	request.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	valid, errors := v.ValidateRequestBody(request)
+	assert.True(t, valid)
+	assert.Len(t, errors, 0)
+
+	body = "name=cheeseburger&patties=23.4"
+
+	request, _ = http.NewRequest(http.MethodPost, "https://things.com/burgers/createBurger",
+		bytes.NewBuffer([]byte(body)))
+	request.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	valid, errors = v.ValidateRequestBody(request)
+
+	assert.False(t, valid)
+	assert.Len(t, errors, 1)
+}
+
 func TestValidateBody_XmlRequest(t *testing.T) {
 	spec := `openapi: 3.1.0
 paths: