Add default name validation options and fix README (#37)

* Normalizes all the name validation options into one each for Marshal and Unmarshal, making the name validation mode constants public.

* Add missing links for name validation options

* Minor fix to the examples used for Marshal and Unmarshal in the README

Author: DQSevilla

README.md

@@ -41,13 +41,13 @@ if err != nil {
 
 fmt.Println("%s", string(b))
 // {
-//     "data": [
+//     "data": {
 //         "id": "1",
 //         "type": "articles",
 //         "attributes": {
 //             "title": "Hello World"
 //         }
-//     ]
+//     }
 // }
 ```
 
@@ -56,7 +56,7 @@ fmt.Println("%s", string(b))
 [jsonapi.Unmarshal](https://pkg.go.dev/github.com/DataDog/jsonapi#Marshal)
 
 ```go
-body := `{"data":[{"id":"1","type":"articles","attributes":{"title":"Hello World"}}]}`
+body := `{"data":{"id":"1","type":"articles","attributes":{"title":"Hello World"}}}`
 
 type Article struct {
     ID    string `jsonapi:"primary,articles"`
@@ -93,8 +93,8 @@ Both [jsonapi.Marshal](https://pkg.go.dev/github.com/DataDog/jsonapi#Marshal) an
 
 | Option | Supports |
 | --- | --- |
-| [jsonapi.MarshalOption](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalOption) | [meta](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalMeta), [json:api](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalJSONAPI), [includes](https://pkg.go.dev/github.com/DataDog/github.com/jsonapi#MarshalInclude), [document links](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalLinks), [sparse fieldsets](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalFields) |
-| [jsonapi.UnmarshalOption](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalOption) | [meta](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalMeta) |
+| [jsonapi.MarshalOption](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalOption) | [meta](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalMeta), [json:api](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalJSONAPI), [includes](https://pkg.go.dev/github.com/DataDog/github.com/jsonapi#MarshalInclude), [document links](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalLinks), [sparse fieldsets](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalFields), [name validation](https://pkg.go.dev/github.com/DataDog/jsonapi#MarshalSetNameValidation) |
+| [jsonapi.UnmarshalOption](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalOption) | [meta](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalMeta), [name validation](https://pkg.go.dev/github.com/DataDog/jsonapi#UnmarshalSetNameValidation) |
 
 ## Non-String Identifiers
 

marshal.go

@@ -25,7 +25,7 @@ type Marshaler struct {
 	included                 []any
 	link                     *Link
 	clientMode               bool
-	memberNameValidationMode memberNameValidationMode
+	memberNameValidationMode MemberNameValidationMode
 
 	// fields support sparse fieldsets https://jsonapi.org/format/#fetching-sparse-fieldsets
 	fields map[string][]string
@@ -86,24 +86,10 @@ func MarshalClientMode() MarshalOption {
 	}
 }
 
-// MarshalStrictNameValidation enables member name validation that is more strict than default.
-//
-// In addition to the basic naming rules from https://jsonapi.org/format/#document-member-names,
-// this option follows guidelines from https://jsonapi.org/recommendations/#naming.
-func MarshalStrictNameValidation() MarshalOption {
+// MarshalSetNameValidation enables a given level of document member name validation.
+func MarshalSetNameValidation(mode MemberNameValidationMode) MarshalOption {
 	return func(m *Marshaler) {
-		m.memberNameValidationMode = strictValidation
-	}
-}
-
-// MarshalDisableNameValidation turns off member name validation, which may be useful for
-// compatibility or performance reasons.
-//
-// Note that this option allows you to use member names which do not conform to the JSON:API spec.
-// See https://jsonapi.org/format/#document-member-names.
-func MarshalDisableNameValidation() MarshalOption {
-	return func(m *Marshaler) {
-		m.memberNameValidationMode = disableValidation
+		m.memberNameValidationMode = mode
 	}
 }
 

marshal_test.go

@@ -764,7 +764,7 @@ func TestMarshalMemberNameValidation(t *testing.T) {
 			_, err := Marshal(tc.given, opts...)
 			is.EqualError(t, tc.expectError, err)
 
-			opts = append(opts, MarshalDisableNameValidation())
+			opts = append(opts, MarshalSetNameValidation(DisableValidation))
 			_, err = Marshal(tc.given, opts...)
 			is.MustNoError(t, err)
 		})
@@ -798,7 +798,7 @@ func BenchmarkMarshal(b *testing.B) {
 			given: articleRelatedComments,
 			opts: []MarshalOption{
 				MarshalInclude(&commentAWithAuthor, &authorA),
-				MarshalDisableNameValidation(),
+				MarshalSetNameValidation(DisableValidation),
 			},
 		}, {
 			name:  "ArticlesComplex",
@@ -808,7 +808,7 @@ func BenchmarkMarshal(b *testing.B) {
 			name:  "ArticlesComplexDisableNameValidation",
 			given: articlesRelatedComplex,
 			opts: append(
-				[]MarshalOption{MarshalDisableNameValidation()},
+				[]MarshalOption{MarshalSetNameValidation(DisableValidation)},
 				articlesRelatedComplexMarshalOptions...,
 			),
 		},

member_names.go

@@ -25,41 +25,42 @@ func init() {
 	strictNameRegex = regexp.MustCompile(`^([a-z]|[a-z]+((\d)|([A-Z\d][a-z\d]+))*([A-Z\d][a-z\d]*[a-z]))$`)
 }
 
-type memberNameValidationMode int
+// MemberNameValidationMode controls how document member names are checked for correctness.
+type MemberNameValidationMode int
 
 const (
-	// defaultValidation verifies that member names are valid according to the spec in
+	// DefaultValidation verifies that member names are valid according to the spec in
 	// https://jsonapi.org/format/#document-member-names.
 	//
 	// Note that this validation mode allows for non-URL-safe member names.
-	defaultValidation memberNameValidationMode = iota
+	DefaultValidation MemberNameValidationMode = iota
 
-	// disableValidation turns off member name validation for convenience and performance-saving
+	// DisableValidation turns off member name validation for convenience or performance-saving
 	// reasons.
 	//
-	// Note that this validation mode allows for member names to not conform to the JSON:API spec.
-	disableValidation
+	// Note that this validation mode allows member names that do NOT conform to the JSON:API spec.
+	DisableValidation
 
-	// strictValidation verifies that member names are both valid according to the spec in
+	// StrictValidation verifies that member names are valid according to the spec in
 	// https://jsonapi.org/format/#document-member-names, and follow recommendations from
 	// https://jsonapi.org/recommendations/#naming.
 	//
 	// Note that these names are always URL-safe.
-	strictValidation
+	StrictValidation
 )
 
-func isValidMemberName(name string, mode memberNameValidationMode) bool {
+func isValidMemberName(name string, mode MemberNameValidationMode) bool {
 	switch mode {
-	case disableValidation:
+	case DisableValidation:
 		return true
-	case strictValidation:
+	case StrictValidation:
 		return strictNameRegex.MatchString(name)
 	default:
 		return defaultNameRegex.MatchString(name)
 	}
 }
 
-func validateMapMemberNames(m map[string]any, mode memberNameValidationMode) error {
+func validateMapMemberNames(m map[string]any, mode MemberNameValidationMode) error {
 	for member, val := range m {
 		if !isValidMemberName(member, mode) {
 			return &MemberNameValidationError{member}
@@ -84,7 +85,7 @@ func validateMapMemberNames(m map[string]any, mode memberNameValidationMode) err
 	return nil
 }
 
-func validateJSONMemberNames(b []byte, mode memberNameValidationMode) error {
+func validateJSONMemberNames(b []byte, mode MemberNameValidationMode) error {
 	var m map[string]any
 	if err := json.Unmarshal(b, &m); err != nil {
 		return fmt.Errorf("unexpected unmarshal failure: %w", err)

member_names_test.go

@@ -10,14 +10,14 @@ func TestIsValidMemberName(t *testing.T) {
 	t.Parallel()
 
 	// associate member name strings with the strictest validation mode they should pass
-	testValidations := map[memberNameValidationMode][]string{
-		strictValidation: {
+	testValidations := map[MemberNameValidationMode][]string{
+		StrictValidation: {
 			"a",
 			"lowercase1with2numerals",
 			"camelCase",
 			"camel12Case9WithNumera1s",
 		},
-		defaultValidation: {
+		DefaultValidation: {
 			"A",
 			"9camelCaseWithNumeralPrefix",
 			"camelCaseWithNumeralSuffix10",
@@ -31,7 +31,7 @@ func TestIsValidMemberName(t *testing.T) {
 			"12",
 			"ƒunky unicode",
 		},
-		disableValidation: {
+		DisableValidation: {
 			"bad%character",
 		},
 	}
@@ -43,17 +43,17 @@ func TestIsValidMemberName(t *testing.T) {
 			t.Run(name, func(t *testing.T) {
 				t.Parallel()
 
-				passesStrict := isValidMemberName(name, strictValidation)
-				passesDefault := isValidMemberName(name, defaultValidation)
+				passesStrict := isValidMemberName(name, StrictValidation)
+				passesDefault := isValidMemberName(name, DefaultValidation)
 
 				switch mode {
-				case strictValidation:
+				case StrictValidation:
 					is.Equal(t, true, passesStrict)
 					is.Equal(t, true, passesDefault)
-				case defaultValidation:
+				case DefaultValidation:
 					is.Equal(t, false, passesStrict)
 					is.Equal(t, true, passesDefault)
-				case disableValidation:
+				case DisableValidation:
 					is.Equal(t, false, passesStrict)
 					is.Equal(t, false, passesDefault)
 				}

unmarshal.go

@@ -11,7 +11,7 @@ import (
 type Unmarshaler struct {
 	unmarshalMeta            bool
 	meta                     any
-	memberNameValidationMode memberNameValidationMode
+	memberNameValidationMode MemberNameValidationMode
 }
 
 // UnmarshalOption allows for configuration of Unmarshaling.
@@ -25,24 +25,10 @@ func UnmarshalMeta(meta any) UnmarshalOption {
 	}
 }
 
-// UnmarshalStrictNameValidation enables member name validation that is more strict than default.
-//
-// In addition to the basic naming rules from https://jsonapi.org/format/#document-member-names,
-// this option follows guidelines from https://jsonapi.org/recommendations/#naming.
-func UnmarshalStrictNameValidation() UnmarshalOption {
+// UnmarshalSetNameValidation enables a given level of document member name validation.
+func UnmarshalSetNameValidation(mode MemberNameValidationMode) UnmarshalOption {
 	return func(m *Unmarshaler) {
-		m.memberNameValidationMode = strictValidation
-	}
-}
-
-// UnmarshalDisableNameValidation turns off member name validation, which may be useful for
-// compatibility or performance reasons.
-//
-// Note that this option allows you to use member names which do not conform to the JSON:API spec.
-// See https://jsonapi.org/format/#document-member-names.
-func UnmarshalDisableNameValidation() UnmarshalOption {
-	return func(m *Unmarshaler) {
-		m.memberNameValidationMode = disableValidation
+		m.memberNameValidationMode = mode
 	}
 }
 

unmarshal_test.go

@@ -699,7 +699,7 @@ func TestUnmarshalMemberNameValidation(t *testing.T) {
 			err := tc.do([]byte(tc.given))
 			is.EqualError(t, tc.expectError, err)
 
-			err = tc.do([]byte(tc.given), UnmarshalDisableNameValidation())
+			err = tc.do([]byte(tc.given), UnmarshalSetNameValidation(DisableValidation))
 			is.MustNoError(t, err)
 		})
 	}
@@ -731,7 +731,7 @@ func BenchmarkUnmarshal(b *testing.B) {
 			name:   "ArticleComplexDisableNameValidation",
 			data:   articleRelatedCommentsNestedWithIncludeBody,
 			target: ArticleRelated{},
-			opts:   []UnmarshalOption{UnmarshalDisableNameValidation()},
+			opts:   []UnmarshalOption{UnmarshalSetNameValidation(DisableValidation)},
 		}, {
 			name:   "ArticlesComplex",
 			data:   articlesRelatedComplexBody,
@@ -741,7 +741,7 @@ func BenchmarkUnmarshal(b *testing.B) {
 			name:   "ArticlesComplexDisableNameValidation",
 			data:   articlesRelatedComplexBody,
 			target: []*ArticleRelated{},
-			opts:   []UnmarshalOption{UnmarshalDisableNameValidation()},
+			opts:   []UnmarshalOption{UnmarshalSetNameValidation(DisableValidation)},
 		},
 	}