feat: support spaceDelimited and pipeDelimited query parameter binding

Implement deserialization for spaceDelimited and pipeDelimited query
parameter styles in both BindQueryParameterWithOptions and
BindRawQueryParameter.

For explode=true, these styles are serialized identically to form
explode=true (each value is a separate key=value pair), so they share
the same code path. For explode=false, the values are split on their
style-specific delimiter (space or pipe) instead of comma.

The BindRawQueryParameter implementation handles all space
representations (%20, +, and literal space) for spaceDelimited.

Fixes #116

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mromaszewicz

bindparam.go

@@ -417,13 +417,17 @@ func BindQueryParameterWithOptions(style string, explode bool, required bool, pa
 	k := t.Kind()
 
 	switch style {
-	case "form":
+	case "form", "spaceDelimited", "pipeDelimited":
 		var parts []string
 		if explode {
 			// ok, the explode case in query arguments is very, very annoying,
 			// because an exploded object, such as /users?role=admin&firstName=Alex
 			// isn't actually present in the parameter array. We have to do
 			// different things based on destination type.
+			//
+			// Note: spaceDelimited and pipeDelimited with explode=true are
+			// serialized identically to form explode=true (each value is a
+			// separate key=value pair), so we share this code path.
 			values, found := queryParams[paramName]
 			var err error
 
@@ -510,7 +514,14 @@ func BindQueryParameterWithOptions(style string, explode bool, required bool, pa
 			if len(values) != 1 {
 				return fmt.Errorf("parameter '%s' is not exploded, but is specified multiple times", paramName)
 			}
-			parts = strings.Split(values[0], ",")
+			switch style {
+			case "spaceDelimited":
+				parts = strings.Split(values[0], " ")
+			case "pipeDelimited":
+				parts = strings.Split(values[0], "|")
+			default:
+				parts = strings.Split(values[0], ",")
+			}
 		}
 		var err error
 		switch k {
@@ -571,8 +582,6 @@ func BindQueryParameterWithOptions(style string, explode bool, required bool, pa
 			return errors.New("deepObjects must be exploded")
 		}
 		return unmarshalDeepObject(dest, paramName, queryParams, required)
-	case "spaceDelimited", "pipeDelimited":
-		return fmt.Errorf("query arguments of style '%s' aren't yet supported", style)
 	default:
 		return fmt.Errorf("style '%s' on parameter '%s' is invalid", style, paramName)
 
@@ -655,10 +664,14 @@ func BindRawQueryParameter(style string, explode bool, required bool, paramName
 	k := t.Kind()
 
 	switch style {
-	case "form":
+	case "form", "spaceDelimited", "pipeDelimited":
 		if explode {
 			// For the explode case, url.ParseQuery is fine — there are no
 			// delimiter commas to confuse with literal commas.
+			//
+			// Note: spaceDelimited and pipeDelimited with explode=true are
+			// serialized identically to form explode=true (each value is a
+			// separate key=value pair), so we share this code path.
 			queryParams, err := url.ParseQuery(rawQuery)
 			if err != nil {
 				return fmt.Errorf("error parsing query string: %w", err)
@@ -707,9 +720,8 @@ func BindRawQueryParameter(style string, explode bool, required bool, paramName
 			return nil
 		}
 
-		// form, explode=false — the core fix.
-		// Use findRawQueryParam to get the still-encoded value, split on
-		// literal ',' (which is the OpenAPI delimiter), then URL-decode
+		// explode=false — use findRawQueryParam to get the still-encoded
+		// value, split on the style-specific delimiter, then URL-decode
 		// each resulting part individually.
 		rawValues, found := findRawQueryParam(rawQuery, paramName)
 		if !found {
@@ -722,7 +734,19 @@ func BindRawQueryParameter(style string, explode bool, required bool, paramName
 			return fmt.Errorf("parameter '%s' is not exploded, but is specified multiple times", paramName)
 		}
 
-		rawParts := strings.Split(rawValues[0], ",")
+		var rawParts []string
+		switch style {
+		case "spaceDelimited":
+			// Normalise all space representations to %20, then split.
+			normalized := strings.ReplaceAll(rawValues[0], "+", "%20")
+			normalized = strings.ReplaceAll(normalized, " ", "%20")
+			rawParts = strings.Split(normalized, "%20")
+		case "pipeDelimited":
+			rawParts = strings.Split(rawValues[0], "|")
+		default:
+			rawParts = strings.Split(rawValues[0], ",")
+		}
+
 		parts := make([]string, len(rawParts))
 		for i, rp := range rawParts {
 			decoded, err := url.QueryUnescape(rp)
@@ -767,8 +791,6 @@ func BindRawQueryParameter(style string, explode bool, required bool, paramName
 			return fmt.Errorf("error parsing query string: %w", err)
 		}
 		return UnmarshalDeepObject(dest, paramName, queryParams)
-	case "spaceDelimited", "pipeDelimited":
-		return fmt.Errorf("query arguments of style '%s' aren't yet supported", style)
 	default:
 		return fmt.Errorf("style '%s' on parameter '%s' is invalid", style, paramName)
 	}

bindparam_test.go

@@ -1045,19 +1045,8 @@ func TestBindRawQueryParameter(t *testing.T) {
 			assert.Contains(t, err.Error(), "exploded")
 		})
 
-		t.Run("spaceDelimited", func(t *testing.T) {
-			var dest []string
-			err := BindRawQueryParameter("spaceDelimited", false, true, "color", "color=a%20b%20c", &dest)
-			assert.Error(t, err)
-			assert.Contains(t, err.Error(), "spaceDelimited")
-		})
-
-		t.Run("pipeDelimited", func(t *testing.T) {
-			var dest []string
-			err := BindRawQueryParameter("pipeDelimited", false, true, "color", "color=a|b|c", &dest)
-			assert.Error(t, err)
-			assert.Contains(t, err.Error(), "pipeDelimited")
-		})
+		// Note: spaceDelimited and pipeDelimited are now supported
+		// and have their own test functions below.
 
 		t.Run("unknown style", func(t *testing.T) {
 			var dest string
@@ -1335,3 +1324,240 @@ func TestBindStyledParameter_HeaderWithCommas(t *testing.T) {
 		assert.Equal(t, []string{"a", "b", "c"}, dest)
 	})
 }
+
+func TestBindQueryParameter_SpaceDelimited(t *testing.T) {
+	t.Run("unexploded int array", func(t *testing.T) {
+		var dest []int
+		q := make(url.Values)
+		q.Set("ids", "3 4 5")
+		err := BindQueryParameterWithOptions("spaceDelimited", false, true, "ids", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("unexploded string array", func(t *testing.T) {
+		var dest []string
+		q := make(url.Values)
+		q.Set("color", "red green blue")
+		err := BindQueryParameterWithOptions("spaceDelimited", false, true, "color", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Equal(t, []string{"red", "green", "blue"}, dest)
+	})
+
+	t.Run("exploded int array", func(t *testing.T) {
+		var dest []int
+		q := make(url.Values)
+		q["ids"] = []string{"3", "4", "5"}
+		err := BindQueryParameterWithOptions("spaceDelimited", true, true, "ids", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("optional missing", func(t *testing.T) {
+		var dest *[]int
+		q := make(url.Values)
+		err := BindQueryParameterWithOptions("spaceDelimited", false, false, "ids", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Nil(t, dest)
+	})
+
+	t.Run("required missing", func(t *testing.T) {
+		var dest []int
+		q := make(url.Values)
+		err := BindQueryParameterWithOptions("spaceDelimited", false, true, "ids", q, &dest, BindQueryParameterOptions{})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "required")
+	})
+}
+
+func TestBindQueryParameter_PipeDelimited(t *testing.T) {
+	t.Run("unexploded int array", func(t *testing.T) {
+		var dest []int
+		q := make(url.Values)
+		q.Set("ids", "3|4|5")
+		err := BindQueryParameterWithOptions("pipeDelimited", false, true, "ids", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("unexploded string array", func(t *testing.T) {
+		var dest []string
+		q := make(url.Values)
+		q.Set("color", "red|green|blue")
+		err := BindQueryParameterWithOptions("pipeDelimited", false, true, "color", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Equal(t, []string{"red", "green", "blue"}, dest)
+	})
+
+	t.Run("exploded int array", func(t *testing.T) {
+		var dest []int
+		q := make(url.Values)
+		q["ids"] = []string{"3", "4", "5"}
+		err := BindQueryParameterWithOptions("pipeDelimited", true, true, "ids", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("optional missing", func(t *testing.T) {
+		var dest *[]int
+		q := make(url.Values)
+		err := BindQueryParameterWithOptions("pipeDelimited", false, false, "ids", q, &dest, BindQueryParameterOptions{})
+		require.NoError(t, err)
+		assert.Nil(t, dest)
+	})
+
+	t.Run("required missing", func(t *testing.T) {
+		var dest []int
+		q := make(url.Values)
+		err := BindQueryParameterWithOptions("pipeDelimited", false, true, "ids", q, &dest, BindQueryParameterOptions{})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "required")
+	})
+}
+
+func TestBindRawQueryParameter_SpaceDelimited(t *testing.T) {
+	t.Run("unexploded with %20", func(t *testing.T) {
+		var dest []int
+		err := BindRawQueryParameter("spaceDelimited", false, true, "ids", "ids=3%204%205", &dest)
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("unexploded with +", func(t *testing.T) {
+		var dest []int
+		err := BindRawQueryParameter("spaceDelimited", false, true, "ids", "ids=3+4+5", &dest)
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("unexploded strings", func(t *testing.T) {
+		var dest []string
+		err := BindRawQueryParameter("spaceDelimited", false, true, "color", "color=red%20green%20blue", &dest)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"red", "green", "blue"}, dest)
+	})
+
+	t.Run("exploded", func(t *testing.T) {
+		var dest []int
+		err := BindRawQueryParameter("spaceDelimited", true, true, "ids", "ids=3&ids=4&ids=5", &dest)
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("optional missing", func(t *testing.T) {
+		var dest *[]int
+		err := BindRawQueryParameter("spaceDelimited", false, false, "ids", "other=val", &dest)
+		require.NoError(t, err)
+		assert.Nil(t, dest)
+	})
+}
+
+func TestBindRawQueryParameter_PipeDelimited(t *testing.T) {
+	t.Run("unexploded", func(t *testing.T) {
+		var dest []int
+		err := BindRawQueryParameter("pipeDelimited", false, true, "ids", "ids=3|4|5", &dest)
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("unexploded strings", func(t *testing.T) {
+		var dest []string
+		err := BindRawQueryParameter("pipeDelimited", false, true, "color", "color=red|green|blue", &dest)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"red", "green", "blue"}, dest)
+	})
+
+	t.Run("exploded", func(t *testing.T) {
+		var dest []int
+		err := BindRawQueryParameter("pipeDelimited", true, true, "ids", "ids=3&ids=4&ids=5", &dest)
+		require.NoError(t, err)
+		assert.Equal(t, []int{3, 4, 5}, dest)
+	})
+
+	t.Run("optional missing", func(t *testing.T) {
+		var dest *[]int
+		err := BindRawQueryParameter("pipeDelimited", false, false, "ids", "other=val", &dest)
+		require.NoError(t, err)
+		assert.Nil(t, dest)
+	})
+}
+
+func TestRoundTripQueryParameter_Delimited(t *testing.T) {
+	tests := []struct {
+		name      string
+		style     string
+		explode   bool
+		paramName string
+		value     interface{}
+		dest      interface{}
+		expected  interface{}
+	}{
+		{
+			name:      "spaceDelimited/false int slice",
+			style:     "spaceDelimited",
+			explode:   false,
+			paramName: "ids",
+			value:     []int{1, 2, 3},
+			dest:      &[]int{},
+			expected:  []int{1, 2, 3},
+		},
+		{
+			name:      "spaceDelimited/false string slice",
+			style:     "spaceDelimited",
+			explode:   false,
+			paramName: "color",
+			value:     []string{"red", "green", "blue"},
+			dest:      &[]string{},
+			expected:  []string{"red", "green", "blue"},
+		},
+		{
+			name:      "spaceDelimited/true int slice",
+			style:     "spaceDelimited",
+			explode:   true,
+			paramName: "ids",
+			value:     []int{1, 2, 3},
+			dest:      &[]int{},
+			expected:  []int{1, 2, 3},
+		},
+		{
+			name:      "pipeDelimited/false int slice",
+			style:     "pipeDelimited",
+			explode:   false,
+			paramName: "ids",
+			value:     []int{1, 2, 3},
+			dest:      &[]int{},
+			expected:  []int{1, 2, 3},
+		},
+		{
+			name:      "pipeDelimited/false string slice",
+			style:     "pipeDelimited",
+			explode:   false,
+			paramName: "color",
+			value:     []string{"red", "green", "blue"},
+			dest:      &[]string{},
+			expected:  []string{"red", "green", "blue"},
+		},
+		{
+			name:      "pipeDelimited/true int slice",
+			style:     "pipeDelimited",
+			explode:   true,
+			paramName: "ids",
+			value:     []int{1, 2, 3},
+			dest:      &[]int{},
+			expected:  []int{1, 2, 3},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			raw, err := StyleParamWithLocation(tt.style, tt.explode, tt.paramName, ParamLocationQuery, tt.value)
+			require.NoError(t, err, "StyleParamWithLocation failed")
+
+			err = BindRawQueryParameter(tt.style, tt.explode, true, tt.paramName, raw, tt.dest)
+			require.NoError(t, err, "BindRawQueryParameter failed for raw=%q", raw)
+
+			actual := reflect.ValueOf(tt.dest).Elem().Interface()
+			assert.Equal(t, tt.expected, actual)
+		})
+	}
+}