jsonmatch: add Irrelevantv1.6.0

3 files changed, 26 insertions, 3 deletions

diff --git a/jsonmatch/diff_test.go b/jsonmatch/diff_test.go
index a59d304..74a976f 100644
--- a/jsonmatch/diff_test.go
+++ b/jsonmatch/diff_test.go
@@ -61,11 +61,13 @@ func TestCanonicalizesActualPayload(t *testing.T) {
 		}
 		AssertEqual(t, match.DiffAgainst(message), nil)
 
-		// changing the type of `data` to map[string]any does not change anything at all;
-		// using the jsonmatch.Object name on this level is mostly syntactic sugar to communicate intent
+		// changing the type of `data` to map[string]any and of `data.qux` to []any does not change anything at all;
+		// using the jsonmatch.Object and jsonmatch.Array names on this level is mostly syntactic sugar to communicate intent;
+		//
+		// also, this tests that jsonmatch.Irrelevant() works as expected
 		match = jsonmatch.Object{
 			"data": map[string]any{
-				"foo": 42,
+				"foo": jsonmatch.Irrelevant(),
 				"bar": "hello world",
 				"qux": []any{5, nil, 15},
 			},
diff --git a/jsonmatch/interface.go b/jsonmatch/interface.go
index de6ef81..047a4b7 100644
--- a/jsonmatch/interface.go
+++ b/jsonmatch/interface.go
@@ -283,3 +283,22 @@ func (f capturedField) MarshalJSON() ([]byte, error) {
 func (f capturedField) UnmarshalJSON(buf []byte) error {
 	return errors.New("cannot unmarshal into jsonmatch.CaptureField()")
 }
+
+type irrelevant struct{}
+
+// Irrelevant returns a slot that can be placed in a jsonmatch.Object or jsonmatch.Array instance
+// to ignore the contents of certain fields or array elements during an assertion.
+//
+// Irrelevant() slots only work inside data structures that DiffAgainst() knows how to recurse into.
+// Please refer to the documentation on type Diffable for details.
+func Irrelevant() any {
+	return irrelevant{}
+}
+
+// MarshalJSON implements the json.Marshaler interface.
+//
+// This implementation ensures that `irrelevant` renders in a readable way
+// when a larger value containing it is serialized for a "type mismatch" or "value mismatch" error message.
+func (irrelevant) MarshalJSON() ([]byte, error) {
+	return []byte(`"<irrelevant>"`), nil
+}
diff --git a/jsonmatch/machinery.go b/jsonmatch/machinery.go
index 7f91f67..32930b6 100644
--- a/jsonmatch/machinery.go
+++ b/jsonmatch/machinery.go
@@ -146,6 +146,8 @@ func getDiffsForValue(path []pathElement, expected, actual any) []Diff {
 		return getDiffsForArray(path, downcasted, actual)
 	case capturedField:
 		return getDiffsForCapturedField(path, expected, actual)
+	case irrelevant:
+		return nil
 	case nil:
 		// this case needs to be handled separately because the code below
 		// cannot deal with reflect.TypeOf(expected) returning nil