Addressed #46

A new function in the `response` package named `ValidateResponseHeaders` will perform a required check, as well as a schema check, if required is set to `true`.

Author: daveshanley

errors/parameters_howtofix.go

@@ -28,4 +28,5 @@ const (
 	HowToFixPathMethod                 = "Add the missing operation to the contract for the path"
 	HowToFixInvalidMaxItems            = "Reduce the number of items in the array to %d or less"
 	HowToFixInvalidMinItems            = "Increase the number of items in the array to %d or more"
+	HowToFixMissingHeader              = "Make sure the service responding sets the required headers with this response code"
 )

parameters/validate_parameter.go

@@ -117,7 +117,10 @@ func ValidateParameterSchema(
 		}
 	} else {
 		decodedString, _ := url.QueryUnescape(rawBlob)
-		_ = json.Unmarshal([]byte(decodedString), &decodedObj)
+		err := json.Unmarshal([]byte(decodedString), &decodedObj)
+		if err != nil {
+			decodedObj = rawBlob
+		}
 		validEncoding = true
 	}
 	// 3. create a new json schema compiler and add the schema to it
@@ -178,8 +181,8 @@ func ValidateParameterSchema(
 					Message:           fmt.Sprintf("%s '%s' cannot be decoded", entity, name),
 					Reason: fmt.Sprintf("%s '%s' is defined as an object, "+
 						"however it failed to be decoded as an object", reasonEntity, name),
-					SpecLine: schema.GoLow().Type.KeyNode.Line,
-					SpecCol:  schema.GoLow().Type.KeyNode.Column,
+					SpecLine: schema.GoLow().RootNode.Line,
+					SpecCol:  schema.GoLow().RootNode.Column,
 					HowToFix: errors.HowToFixDecodingError,
 				})
 			}

responses/validate_body.go

@@ -90,6 +90,7 @@ func (v *responseBodyValidator) ValidateResponseBodyWithPathItem(request *http.R
 		if operation.Responses.Default != nil && operation.Responses.Default.Content != nil {
 			// check content type has been defined in the contract
 			if mediaType, ok := operation.Responses.Default.Content.Get(mediaTypeSting); ok {
+				foundResponse = operation.Responses.Default
 				validationErrors = append(validationErrors,
 					v.checkResponseSchema(request, response, contentType, mediaType)...)
 			} else {
@@ -108,6 +109,15 @@ func (v *responseBodyValidator) ValidateResponseBodyWithPathItem(request *http.R
 		}
 	}
 
+	if foundResponse != nil {
+		// check for headers in the response
+		if foundResponse.Headers != nil {
+			if ok, herrs := ValidateResponseHeaders(request, response, foundResponse.Headers); !ok {
+				validationErrors = append(validationErrors, herrs...)
+			}
+		}
+	}
+
 	errors.PopulateValidationErrors(validationErrors, request, pathFound)
 
 	if len(validationErrors) > 0 {

responses/validate_headers.go

@@ -0,0 +1,90 @@
+// Copyright 2023-2025 Princess Beef Heavy Industries, LLC / Dave Shanley
+// https://pb33f.io
+
+package responses
+
+import (
+	"fmt"
+	"github.com/pb33f/libopenapi-validator/helpers"
+	"github.com/pb33f/libopenapi-validator/parameters"
+	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
+	lowv3 "github.com/pb33f/libopenapi/datamodel/low/v3"
+	"github.com/pb33f/libopenapi/orderedmap"
+
+	"net/http"
+	"strings"
+
+	"github.com/pb33f/libopenapi-validator/config"
+	"github.com/pb33f/libopenapi-validator/errors"
+)
+
+// ValidateResponseHeaders validates the response headers against the OpenAPI spec.
+func ValidateResponseHeaders(
+	request *http.Request,
+	response *http.Response,
+	headers *orderedmap.Map[string, *v3.Header],
+	opts ...config.Option,
+) (bool, []*errors.ValidationError) {
+	options := config.NewValidationOptions(opts...)
+
+	// locate headers
+	type headerPair struct {
+		name  string
+		value []string
+		model *v3.Header
+	}
+	locatedHeaders := make(map[string]headerPair)
+	var validationErrors []*errors.ValidationError
+	// iterate through the response headers
+	for name, v := range response.Header {
+		// check if the model is in the spec
+		for k, header := range headers.FromOldest() {
+			if strings.EqualFold(k, name) {
+				locatedHeaders[strings.ToLower(name)] = headerPair{
+					name:  k,
+					value: v,
+					model: header,
+				}
+			}
+		}
+	}
+
+	// determine if any required headers are missing from the response
+	for name, header := range headers.FromOldest() {
+		if header.Required {
+			if _, ok := locatedHeaders[strings.ToLower(name)]; !ok {
+				validationErrors = append(validationErrors, &errors.ValidationError{
+					ValidationType:    helpers.ResponseBodyValidation,
+					ValidationSubType: helpers.ParameterValidationHeader,
+					Message:           "Missing required model",
+					Reason:            fmt.Sprintf("Required model '%s' was not found in response", name),
+					SpecLine:          header.GoLow().KeyNode.Line,
+					SpecCol:           header.GoLow().KeyNode.Column,
+					HowToFix:          errors.HowToFixMissingHeader,
+					RequestPath:       request.URL.Path,
+					RequestMethod:     request.Method,
+				})
+			}
+		}
+	}
+
+	// validate the model schemas if they are set.
+	for h, header := range locatedHeaders {
+		if header.model.Schema != nil {
+			schema := header.model.Schema.Schema()
+			if schema != nil && header.model.Required {
+
+				for _, headerValue := range header.value {
+					validationErrors = append(validationErrors,
+						parameters.ValidateParameterSchema(schema, nil, headerValue, "header",
+							"response header", h, helpers.ResponseBodyValidation, lowv3.HeadersLabel, options)...)
+
+				}
+			}
+		}
+	}
+	if len(validationErrors) == 0 {
+		return true, nil
+	}
+	return false, validationErrors
+}

responses/validate_headers_test.go

@@ -0,0 +1,85 @@
+// Copyright 2023-2025 Princess Beef Heavy Industries, LLC / Dave Shanley
+// https://pb33f.io
+
+package responses
+
+import (
+	"github.com/pb33f/libopenapi"
+	"github.com/stretchr/testify/assert"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestValidateResponseHeaders(t *testing.T) {
+	spec := `openapi: "3.0.0"
+info:
+  title: Healthcheck
+  version: '0.1.0'
+paths:
+  /health:
+    get:
+      responses:
+        '200':
+          headers:
+            chicken-nuggets:
+              description: chicken nuggets response
+              required: true
+              schema:
+                type: integer
+          description: pet response`
+
+	doc, _ := libopenapi.NewDocument([]byte(spec))
+
+	m, _ := doc.BuildV3Model()
+
+	// build a request
+	request, _ := http.NewRequest(http.MethodGet, "https://things.com/health", nil)
+
+	// simulate a request/response
+	res := httptest.NewRecorder()
+	handler := func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Chicken-Cakes", "I should fail")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(nil)
+	}
+
+	// fire the request
+	handler(res, request)
+
+	// record response
+	response := res.Result()
+
+	headers := m.Model.Paths.PathItems.GetOrZero("/health").Get.Responses.Codes.GetOrZero("200").Headers
+
+	// validate!
+	valid, errors := ValidateResponseHeaders(request, response, headers)
+
+	assert.False(t, valid)
+	assert.Len(t, errors, 1)
+	assert.Equal(t, errors[0].Message, "Missing required model")
+	assert.Equal(t, errors[0].Reason, "Required model 'chicken-nuggets' was not found in response")
+
+	res = httptest.NewRecorder()
+	handler = func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Chicken-Nuggets", "I should fail")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(nil)
+	}
+
+	// fire the request
+	handler(res, request)
+
+	response = res.Result()
+
+	headers = m.Model.Paths.PathItems.GetOrZero("/health").Get.Responses.Codes.GetOrZero("200").Headers
+
+	// validate!
+	valid, errors = ValidateResponseHeaders(request, response, headers)
+
+	assert.False(t, valid)
+	assert.Len(t, errors, 1)
+	assert.Equal(t, errors[0].Message, "header 'chicken-nuggets' failed to validate")
+	assert.Equal(t, errors[0].Reason, "response header 'chicken-nuggets' is defined as an integer, however it failed to pass a schema validation")
+
+}

validator_examples_test.go

@@ -261,3 +261,123 @@ func ExampleNewValidator_validateHttpResponse() {
 	// Output: Type: response, Failure: 200 response body for '/pet/findByStatus' failed to validate schema
 	// Schema Error: got string, want integer, Line: 19, Col: 27
 }
+
+func ExampleNewValidator_testResponseHeaders() {
+	// 1. Load the OpenAPI 3+ spec into a byte array
+	petstore := []byte(`openapi: "3.0.0"
+info:
+  title: Healthcheck
+  version: '0.1.0'
+paths:
+  /health:
+    get:
+      responses:
+        '200':
+          headers:
+            chicken-nuggets:
+              description: chicken nuggets response
+              required: true
+              schema:
+                type: integer
+          description: pet response`)
+
+	// 2. Create a new OpenAPI document using libopenapi
+	document, docErrs := libopenapi.NewDocument(petstore)
+
+	if docErrs != nil {
+		panic(docErrs)
+	}
+
+	// 3. Create a new validator
+	docValidator, validatorErrs := NewValidator(document)
+
+	if validatorErrs != nil {
+		panic(validatorErrs)
+	}
+
+	// 6. Create a new *http.Request (normally, this would be where the host application will pass in the request)
+	request, _ := http.NewRequest(http.MethodGet, "/health", nil)
+
+	// 7. Simulate a request/response, in this case the contract returns a 200 with an array of pets.
+	// Normally, this would be where the host application would pass in the response.
+	recorder := httptest.NewRecorder()
+	handler := func(w http.ResponseWriter, r *http.Request) {
+		// set return content type.
+		w.Header().Set("Chicken-Nuggets", "I am a chicken nugget, and not an integer")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(nil)
+	}
+
+	// simulate request/response
+	handler(recorder, request)
+
+	// 7. Validate the response only
+	valid, validationErrs := docValidator.ValidateHttpResponse(request, recorder.Result())
+
+	if !valid {
+		for _, e := range validationErrs {
+			// 5. Handle the error
+			fmt.Printf("Type: %s, Failure: %s\n", e.ValidationType, e.Message)
+		}
+	}
+	// Output: Type: response, Failure: header 'chicken-nuggets' failed to validate
+}
+
+func ExampleNewValidator_responseHeaderNotRequired() {
+	// 1. Load the OpenAPI 3+ spec into a byte array
+	petstore := []byte(`openapi: "3.0.0"
+info:
+  title: Healthcheck
+  version: '0.1.0'
+paths:
+  /health:
+    get:
+      responses:
+        '200':
+          headers:
+            chicken-nuggets:
+              description: chicken nuggets response
+              required: false
+              schema:
+                type: integer
+          description: pet response`)
+
+	// 2. Create a new OpenAPI document using libopenapi
+	document, docErrs := libopenapi.NewDocument(petstore)
+
+	if docErrs != nil {
+		panic(docErrs)
+	}
+
+	// 3. Create a new validator
+	docValidator, validatorErrs := NewValidator(document)
+
+	if validatorErrs != nil {
+		panic(validatorErrs)
+	}
+
+	// 6. Create a new *http.Request (normally, this would be where the host application will pass in the request)
+	request, _ := http.NewRequest(http.MethodGet, "/health", nil)
+
+	// 7. Simulate a request/response, in this case the contract returns a 200 with an array of pets.
+	// Normally, this would be where the host application would pass in the response.
+	recorder := httptest.NewRecorder()
+	handler := func(w http.ResponseWriter, r *http.Request) {
+		// set return content type.
+		w.Header().Set("Chicken-Nuggets", "I am a chicken nugget, and not an integer")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(nil)
+	}
+
+	// simulate request/response
+	handler(recorder, request)
+
+	// 7. Validate the response only
+	valid, _ := docValidator.ValidateHttpResponse(request, recorder.Result())
+
+	if !valid {
+		panic("the header is not required, it should not fail")
+	}
+	fmt.Println("Header is not required, validation passed")
+	// Output: Header is not required, validation passed
+}