@@ -8,39 +8,73 @@ Go implementation of [JSON Pointer (RFC 6901)](https://datatracker.ietf.org/doc/
 and mutating JSON documents represented as Go values. Unlike most implementations, it works not only with
 `map[string]any` and slices, but also with Go structs (resolved via `json` struct tags and reflection).
 
-See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details.
+### Package layout
 
-### Package layout (single package)
+Two packages in one module (`github.com/go-openapi/jsonpointer`):
 
 | File | Contents |
 |------|----------|
-| `pointer.go` | Core types (`Pointer`, `JSONPointable`, `JSONSetable`), `New`, `Get`, `Set`, `Offset`, `Escape`/`Unescape` |
-| `errors.go` | Sentinel errors: `ErrPointer`, `ErrInvalidStart`, `ErrUnsupportedValueType` |
+| `pointer.go` | `Pointer`, `New`, `Get`, `Set`, `Offset`, `GetForToken`, `SetForToken`, `Escape`/`Unescape`, and the reflection helpers |
+| `ifaces.go` | `JSONPointable`, `JSONSetable`, `NameProvider` interfaces |
+| `options.go` | `Option`, `WithNameProvider`, `SetDefaultNameProvider`, `UseGoNameProvider`, `DefaultNameProvider` |
+| `errors.go` | Sentinel errors and their constructors |
+| `jsonname/name_provider.go` | `NameProvider` — the default, tag-only resolver (`DefaultJSONNameProvider`) |
+| `jsonname/go_name_provider.go` | `GoNameProvider` — the alternative resolver, follows `encoding/json` rules |
 
 ### Key API
 
 - `New(string) (Pointer, error)` — parse a JSON pointer string (e.g. `"/foo/0/bar"`)
-- `Pointer.Get(document any) (any, reflect.Kind, error)` — retrieve a value
-- `Pointer.Set(document, value any) (any, error)` — set a value (document must be pointer/map/slice)
+- `Pointer.Get(document any, opts ...Option) (any, reflect.Kind, error)` — retrieve a value
+- `Pointer.Set(document, value any, opts ...Option) (any, error)` — set a value (document must be a pointer, map or slice)
 - `Pointer.Offset(jsonString string) (int64, error)` — byte offset of token in raw JSON
 - `GetForToken` / `SetForToken` — single-level convenience helpers
 - `Escape` / `Unescape` — RFC 6901 token escaping (`~0` ↔ `~`, `~1` ↔ `/`)
 
 Custom types can implement `JSONPointable` (for Get) or `JSONSetable` (for Set) to bypass reflection.
 
+Sentinel errors: `ErrPointer`, `ErrInvalidStart`, `ErrUnsupportedValueType`, `ErrDashToken`.
+Errors raised by the package wrap `ErrPointer`. Errors returned by a caller's `JSONLookup` or
+`JSONSet` are passed through unchanged, so `errors.Is(err, ErrPointer)` is false for those.
+
+### Name providers
+
+Two implementations of the `NameProvider` interface resolve go field names to json names. They
+differ, and the difference is load-bearing for most "why is my field unreachable" questions:
+
+- `jsonname.NameProvider` (the default, `jsonname.DefaultJSONNameProvider`): only fields carrying a
+  non-empty `json` tag are reachable.
+- `jsonname.GoNameProvider` (opt in with `UseGoNameProvider()` or `WithNameProvider`): follows
+  `encoding/json`, so untagged exported fields are reachable under their go name.
+
 ### Dependencies
 
-- `github.com/go-openapi/swag/jsonname` — struct tag → JSON field name resolution
 - `github.com/go-openapi/testify/v2` — test-only assertions
 
-### Notable historical design decisions
+The module has no non-test dependency. `jsonname` is a subpackage of this repository, not the
+similarly named `github.com/go-openapi/swag/jsonname`.
 
-See also .claude/plans/ROADMAP.md.
+### Notable design decisions
 
-- Struct fields **must** have a `json` tag to be reachable; untagged fields are ignored
-  (differs from `encoding/json` which defaults to the Go field name).
-- Anonymous embedded struct fields are traversed only if tagged.
+- Under the default provider, struct fields **must** have a `json` tag to be reachable; untagged
+  fields are ignored (differs from `encoding/json`, which defaults to the go field name). Use
+  `UseGoNameProvider()` for `encoding/json` semantics.
+- An anonymous (embedded) field is walked for the fields it promotes, and its own `json` tag is
+  ignored — tagged or not, the tag never becomes a reachable key.
+- Embedding is traversed through a pointer (`*Base`). Resolving a promoted field on a value whose
+  embedded pointer is nil reports an error; it does not allocate the intermediate struct.
+- An anonymous field that is not a struct (e.g. an embedded named slice) promotes nothing and is
+  unreachable.
+- Maps must be keyed by a string type. A named string type is converted; `map[int]V` and friends
+  cannot be addressed by a pointer and report an error.
+- `Set` with a nil value (what `encoding/json` decodes a JSON null into) writes the zero value when
+  the target can hold nil — interface, pointer, map, slice, chan, func. On a target that cannot
+  represent null (a `string` field, an element of `[]int`) it reports an error rather than
+  substituting a zero value. Setting a map member to nil keeps the member; it does not delete it.
 - The RFC 6901 `"-"` array suffix is supported on `Pointer.Set` as an append
   operation (RFC 6902 convention). On `Pointer.Get` / `Pointer.Offset` it is
   always an error per RFC 6901 §4.
 
+### Conventions
+
+See `.claude/rules/` for contribution, linting, go and technical-writing conventions.
+Format with `golangci-lint fmt`, and check a change with `golangci-lint run --new-from-rev master`.
@@ -3,7 +3,10 @@
 
 package jsonpointer
 
-import "fmt"
+import (
+	"fmt"
+	"reflect"
+)
 
 type pointerError string
 
@@ -47,6 +50,24 @@ func errInvalidReference(token string) error {
 	return fmt.Errorf("invalid token reference %q: %w", token, ErrPointer)
 }
 
+func errNoField(token string) error {
+	return fmt.Errorf("object has no field %q: %w", token, ErrPointer)
+}
+
+// errUnreachableField reports a field that exists on the type but cannot be reached on this value,
+// because it is promoted through a nil embedded pointer.
+func errUnreachableField(name string, cause error) error {
+	return fmt.Errorf("cannot reach field %q: %w: %w", name, cause, ErrPointer)
+}
+
+// errMapKey reports a reference token that cannot serve as a key of the target map type.
+//
+// JSON object member names are strings, so only maps keyed by a string type (or by an interface
+// type a string satisfies) can be addressed by a JSON pointer.
+func errMapKey(token string, mapType reflect.Type) error {
+	return fmt.Errorf("can't use token %q as a key of map type %v: %w", token, mapType, ErrPointer)
+}
+
 func errDashOnGet() error {
 	return fmt.Errorf("cannot resolve %q token on get: %w: %w", dashToken, ErrDashToken, ErrPointer)
 }
 
@@ -46,7 +46,7 @@ func (n *GoNameProvider) GetJSONNames(subject any) []string {
 	n.lock.Lock()
 	defer n.lock.Unlock()
 
-	tpe := reflect.Indirect(reflect.ValueOf(subject)).Type()
+	tpe := typeOfSubject(subject)
 	names := n.nameIndexFor(tpe)
 
 	res := make([]string, 0, len(names.jsonNames))
@@ -59,7 +59,7 @@ func (n *GoNameProvider) GetJSONNames(subject any) []string {
 
 // GetJSONName gets the json name for a go property name.
 func (n *GoNameProvider) GetJSONName(subject any, name string) (string, bool) {
-	tpe := reflect.Indirect(reflect.ValueOf(subject)).Type()
+	tpe := typeOfSubject(subject)
 
 	return n.GetJSONNameForType(tpe, name)
 }
@@ -77,7 +77,7 @@ func (n *GoNameProvider) GetJSONNameForType(tpe reflect.Type, name string) (stri
 
 // GetGoName gets the go name for a json property name.
 func (n *GoNameProvider) GetGoName(subject any, name string) (string, bool) {
-	tpe := reflect.Indirect(reflect.ValueOf(subject)).Type()
+	tpe := typeOfSubject(subject)
 
 	return n.GetGoNameForType(tpe, name)
 }
@@ -132,7 +132,7 @@ func buildGoNameIndex(tpe reflect.Type) nameIndex {
 //
 //nolint:gocognit // everything is inlined to help the compiler determine what escapes and what doesn't
 func collectGoFields(tpe reflect.Type) []fieldEntry {
-	if tpe.Kind() != reflect.Struct {
+	if tpe == nil || tpe.Kind() != reflect.Struct {
 		return nil
 	}
 
 
@@ -47,7 +47,13 @@ func buildnameIndex(tpe reflect.Type, idx, reverseIdx map[string]string) {
 		}
 
 		if targetDes.Anonymous { // walk embedded structures tree down first
-			buildnameIndex(targetDes.Type, idx, reverseIdx)
+			// An embedded field is not necessarily a struct: it may be a pointer to a struct, or a named
+			// non-struct type (e.g. an embedded named slice or map). Only struct shapes carry promoted
+			// fields worth indexing; anything else contributes no json name and must not be walked.
+			if embedded := structTypeOf(targetDes.Type); embedded != nil {
+				buildnameIndex(embedded, idx, reverseIdx)
+			}
+
 			continue
 		}
 
@@ -73,18 +79,57 @@ func buildnameIndex(tpe reflect.Type, idx, reverseIdx map[string]string) {
 }
 
 func newNameIndex(tpe reflect.Type) nameIndex {
+	tpe = structTypeOf(tpe)
+	if tpe == nil {
+		// only struct shapes carry json names: anything else indexes to nothing.
+		return nameIndex{jsonNames: map[string]string{}, goNames: map[string]string{}}
+	}
+
 	idx := make(map[string]string, tpe.NumField())
 	reverseIdx := make(map[string]string, tpe.NumField())
 
 	buildnameIndex(tpe, idx, reverseIdx)
 	return nameIndex{jsonNames: idx, goNames: reverseIdx}
 }
 
+// structTypeOf reduces tpe to the struct type it designates, dereferencing a pointer type.
+//
+// It returns nil when tpe is nil or does not designate a struct, so that callers may treat
+// "nothing to index here" uniformly instead of panicking in [reflect.Type.NumField].
+func structTypeOf(tpe reflect.Type) reflect.Type {
+	if tpe == nil {
+		return nil
+	}
+
+	if tpe.Kind() == reflect.Pointer {
+		tpe = tpe.Elem()
+	}
+
+	if tpe.Kind() != reflect.Struct {
+		return nil
+	}
+
+	return tpe
+}
+
+// typeOfSubject returns the type of a document subject, dereferencing pointers.
+//
+// It returns nil for an untyped nil subject, which resolves to an empty name index rather than
+// panicking in [reflect.Value.Type].
+func typeOfSubject(subject any) reflect.Type {
+	rValue := reflect.Indirect(reflect.ValueOf(subject))
+	if !rValue.IsValid() {
+		return nil
+	}
+
+	return rValue.Type()
+}
+
 // GetJSONNames gets all the json property names for a type.
 func (n *NameProvider) GetJSONNames(subject any) []string {
 	n.lock.Lock()
 	defer n.lock.Unlock()
-	tpe := reflect.Indirect(reflect.ValueOf(subject)).Type()
+	tpe := typeOfSubject(subject)
 	names, ok := n.index[tpe]
 	if !ok {
 		names = n.makeNameIndex(tpe)
@@ -99,7 +144,7 @@ func (n *NameProvider) GetJSONNames(subject any) []string {
 
 // GetJSONName gets the json name for a go property name.
 func (n *NameProvider) GetJSONName(subject any, name string) (string, bool) {
-	tpe := reflect.Indirect(reflect.ValueOf(subject)).Type()
+	tpe := typeOfSubject(subject)
 	return n.GetJSONNameForType(tpe, name)
 }
 
@@ -117,7 +162,7 @@ func (n *NameProvider) GetJSONNameForType(tpe reflect.Type, name string) (string
 
 // GetGoName gets the go name for a json property name.
 func (n *NameProvider) GetGoName(subject any, name string) (string, bool) {
-	tpe := reflect.Indirect(reflect.ValueOf(subject)).Type()
+	tpe := typeOfSubject(subject)
 	return n.GetGoNameForType(tpe, name)
 }
 
 
@@ -4,6 +4,7 @@
 package jsonname
 
 import (
+	"fmt"
 	"reflect"
 	"testing"
 
@@ -124,3 +125,100 @@ func TestNameProvider(t *testing.T) {
 
 	assert.Len(t, provider.index, 1)
 }
+
+type EmbeddedBase struct {
+	ID string `json:"id"`
+}
+
+// WithEmbeddedPointer embeds a pointer to a struct, the shape that used to panic in
+// buildnameIndex with "reflect: NumField of non-struct type *jsonname.EmbeddedBase".
+type WithEmbeddedPointer struct {
+	*EmbeddedBase
+
+	Name string `json:"name"`
+}
+
+type NamedSlice []string
+
+// WithEmbeddedNonStruct embeds a named slice type, which carries no field to promote.
+type WithEmbeddedNonStruct struct {
+	NamedSlice
+
+	Name string `json:"name"`
+}
+
+type WithEmbeddedTaggedNonStruct struct {
+	NamedSlice `json:"list"`
+
+	Name string `json:"name"`
+}
+
+func TestNameProviderAnonymousFields(t *testing.T) {
+	t.Run("should promote fields of an embedded pointer to struct", func(t *testing.T) {
+		provider := NewNameProvider()
+
+		nm, ok := provider.GetGoName(WithEmbeddedPointer{EmbeddedBase: nil, Name: ""}, "id")
+		assert.TrueT(t, ok)
+		assert.EqualT(t, "ID", nm)
+
+		nm, ok = provider.GetGoName(WithEmbeddedPointer{EmbeddedBase: nil, Name: ""}, "name")
+		assert.TrueT(t, ok)
+		assert.EqualT(t, "Name", nm)
+	})
+
+	t.Run("should index a struct embedding a non-struct type", func(t *testing.T) {
+		provider := NewNameProvider()
+
+		nm, ok := provider.GetGoName(WithEmbeddedNonStruct{NamedSlice: nil, Name: ""}, "name")
+		assert.TrueT(t, ok)
+		assert.EqualT(t, "Name", nm)
+	})
+
+	t.Run("should index a struct embedding a tagged non-struct type", func(t *testing.T) {
+		provider := NewNameProvider()
+
+		nm, ok := provider.GetGoName(WithEmbeddedTaggedNonStruct{NamedSlice: nil, Name: ""}, "name")
+		assert.TrueT(t, ok)
+		assert.EqualT(t, "Name", nm)
+	})
+}
+
+func TestNameProviderNonStructSubjects(t *testing.T) {
+	// a subject that is not a struct carries no json name: it indexes to nothing rather than
+	// panicking in reflect.Type.NumField or reflect.Value.Type.
+	for _, subject := range []any{
+		map[string]any{"a": 1},
+		42,
+		"a string",
+		[]int{1, 2},
+		nil,
+	} {
+		t.Run(fmt.Sprintf("subject %T", subject), func(t *testing.T) {
+			t.Run("NameProvider", func(t *testing.T) {
+				provider := NewNameProvider()
+				assert.Empty(t, provider.GetJSONNames(subject))
+
+				nm, ok := provider.GetGoName(subject, "a")
+				assert.FalseT(t, ok)
+				assert.Empty(t, nm)
+
+				nm, ok = provider.GetJSONName(subject, "A")
+				assert.FalseT(t, ok)
+				assert.Empty(t, nm)
+			})
+
+			t.Run("GoNameProvider", func(t *testing.T) {
+				provider := NewGoNameProvider()
+				assert.Empty(t, provider.GetJSONNames(subject))
+
+				nm, ok := provider.GetGoName(subject, "a")
+				assert.FalseT(t, ok)
+				assert.Empty(t, nm)
+
+				nm, ok = provider.GetJSONName(subject, "A")
+				assert.FalseT(t, ok)
+				assert.Empty(t, nm)
+			})
+		})
+	}
+}