@@ -8,39 +8,76 @@ 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`.
+
+Tests run with `-race`. CI runs `{ubuntu, macos, windows} x {stable, oldstable}`, via the shared
+`go-openapi/ci-workflows/.github/workflows/go-test.yml`.
@@ -5,7 +5,8 @@ paths:
 
 # Contribution rules (go-openapi)
 
-Read `.github/CONTRIBUTING.md` before opening a pull request.
+Read the go-openapi contribution guide before opening a pull request, plus the sibling rules in
+this directory: go conventions, linting, testing, github workflows and technical writing.
 
 ## Commit hygiene
 
@@ -41,12 +42,15 @@ go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
 - Aim for at least 80% coverage of your patch.
 - Run the full test suite before submitting:
 
-For mono-repos:
 ```sh
-go test work ./...
+go test ./...
 ```
 
-For single module repos:
+In a mono-repo, run it once per module (a Go workspace does not give `go test` a whole-workspace
+target).
+
+Run the race detector too, since CI does:
+
 ```sh
-go test ./...
+go test -race ./...
 ```
@@ -10,7 +10,17 @@ golangci-lint run
 ```
 
 Config: `.golangci.yml` — posture is `default: all` with explicit disables.
-See `docs/STYLE.md` for the rationale behind each disabled linter.
+Each disable is listed there under `linters.disable`.
+
+Format with `golangci-lint fmt` (not `gofmt` or `gofumpt` directly — the config drives which
+formatters run).
+
+Check a change against the base branch before pushing, so pre-existing reports in untouched code
+do not drown out your own:
+
+```sh
+golangci-lint run --new-from-rev master
+```
 
 Key rules:
 - Every `//nolint` directive **must** have an inline comment explaining why.
 
@@ -6,42 +6,81 @@ Go implementation of [JSON Pointer (RFC 6901)](https://datatracker.ietf.org/doc/
 and mutating JSON documents represented as Go values. Works with `map[string]any`, slices, and Go structs
 (resolved via `json` struct tags and reflection).
 
-## Package Layout (single package)
+## Package Layout
+
+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. The
+difference drives 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.
+
 ## Design Decisions
 
-- Struct fields **must** have a `json` tag to be reachable; untagged fields are ignored.
-- Anonymous embedded struct fields are traversed only if tagged.
-- The RFC 6901 `"-"` array suffix (append) is **not** implemented.
+- Under the default provider, struct fields **must** have a `json` tag to be reachable; untagged
+  fields are ignored. 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` and `Pointer.Offset` it is always an error per
+  RFC 6901 §4. See `ErrDashToken`.
 
 ## Dependencies
 
-- `github.com/go-openapi/swag/jsonname` — struct tag to JSON field name resolution
 - `github.com/go-openapi/testify/v2` — test-only assertions (zero-dep fork of `stretchr/testify`)
 
+The module has no non-test dependency. `jsonname` is a subpackage of this repository, not the
+similarly named `github.com/go-openapi/swag/jsonname`.
+
 ## Conventions
 
 - All `.go` files must have SPDX license headers (Apache-2.0).
 - Commits require DCO sign-off (`git commit -s`).
-- Linting: `golangci-lint run` — config in `.golangci.yml` (posture: `default: all` with explicit disables).
+- Linting: `golangci-lint run` — config in `.golangci.yml` (posture: `default: all` with explicit
+  disables). Format with `golangci-lint fmt`, and check a change with
+  `golangci-lint run --new-from-rev master`.
 - Every `//nolint` directive **must** have an inline comment explaining why.
-- Tests: `go test ./...` with `-race`. CI runs on `{ubuntu, macos, windows} x {stable, oldstable}`.
+- Tests: `go test ./...` with `-race`. CI runs `{ubuntu, macos, windows} x {stable, oldstable}`,
+  via the shared `go-openapi/ci-workflows/.github/workflows/go-test.yml`.
 - Test framework: `github.com/go-openapi/testify/v2` (not `stretchr/testify`).
 
 See `.github/copilot/` (symlinked to `.claude/rules/`) for detailed rules on Go conventions, linting, testing, and contributions.
@@ -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)
 }