--- sidebar_label: "FAQ" title: "FAQ - CyberGo JSON | Common Questions Quick Reference" description: "CyberGo JSON FAQ: package functions vs Processor, missing-path semantics, float64 numbers, Set purity, stdlib migration differences, and cache tuning." sidebar_position: 1 --- # FAQ ## How do I choose between package-level functions and a Processor? **Answer:** For occasional JSON operations, scripts, or when you do not want to manage lifecycles, use package-level functions (`json.GetString` etc., backed by the global processor). When you need custom configuration (security mode, cache parameters), hooks/auditing/runtime stats, or high-frequency queries, use a Processor (`p, err := json.New(cfg)`). | Dimension | Package functions | Processor | |------|----------|-----------| | Creation | None required | `json.New(cfg)` | | Configuration | Trailing `cfg ...Config` | Configured once at creation | | Pre-parse / path compilation | Not supported | `PreParse` / `CompilePath` | | Resource management | Managed globally | Manual `Close()` | For the full comparison and decision tree, see [Processor Getting Started](../getting-started/processor-guide#package-functions-vs-processor). ## What exactly is returned when a path is not found? **Answer:** It depends on the call, and "key does not exist" behaves differently from "array index out of range": | Call | Object key missing | Array index out of range | |------|--------------|--------------| | `json.Get` | `(nil, ErrPathNotFound)` | `(nil, nil)` — **no error** | | `json.GetString` and other typed functions | Zero value or the passed default | Zero value or the passed default | | `json.SafeGet` | `Exists: false` | `Exists: true` with a nil value | When an array index is out of range, `Get` does not error (the result is nil), so deciding "does this element exist" requires checking the return value, not just err. Full rules in [Syntax Pitfalls](../getting-started/path-syntax#what-are-the-syntax-pitfalls). ## Why is the number I retrieved a float64? **Answer:** `Get` returns `any`, and JSON numbers are always decoded as `float64`: ```go data := `{"version": 1}` val, _ := json.Get(data, "version") // val is float64(1), not int i := json.GetInt(data, "version") // use a typed function when you need int ``` Large integers beyond `float64` precision (such as snowflake IDs) get rounded — use `Config.PreserveNumbers` to keep the original number text, or `Decoder.UseNumber()` to get `json.Number`. ## Why did the original JSON not change after calling Set? **Answer:** `Set`/`Delete` are pure-function style: they return a **new string** with the modification applied; the original is untouched. Discarding the return value is the most common beginner bug: ```go package main import ( "fmt" "github.com/cybergodev/json" ) func main() { data := `{"name": "old"}` updated, err := json.Set(data, "name", "new") if err != nil { panic(err) } fmt.Println(data) // {"name": "old"} — original unchanged fmt.Println(updated) // {"name":"new"} } ``` When modifying multiple fields, use `SetMultiple` to do it in one call instead of chaining `Set`. ## What happens when Set uses an out-of-range index? **Answer:** Unlike the query side's "zero value, no error" — under the default configuration (`CreatePaths: true`), `Set` pads the array with `null` up to the target index: ```go updated, _ := json.Set(`{"items":[1,2,3]}`, "items[5]", "x") // {"items":[1,2,3,null,null,"x"]} ``` To append at the end, use `items[+]` (the preceding path must be an existing array); do not rely on out-of-range indices. For how index, slice, and modification each handle out-of-range values, see [Syntax Pitfalls](../getting-started/path-syntax#what-are-the-syntax-pitfalls). ## Why does a missed field extraction not report an error? **Answer:** A "miss" in field extraction `{name,email}` is silent — `Get` returns `(nil, nil)`, with neither a value nor an error. In multi-field extraction, as long as one field exists, an object containing only the hit fields is returned. Therefore you cannot use `err != nil` to decide whether an extraction hit; check the return value itself. Also note that single-field and multi-field extraction return different shapes: `user{name}` returns the bare value, while `user{id,name}` returns an object. See [Syntax Pitfalls](../getting-started/path-syntax#what-are-the-syntax-pitfalls). ## How do I access keys containing dots or brackets? **Answer:** Two ways: escape with a backslash in dot syntax, or switch to JSON Pointer (starting with `/`, where dots and brackets are simply part of the key name, no escaping needed): ```go data := `{"a.b": 1, "c[0]": 2}` json.GetInt(data, "a\\.b") // 1 — the Go literal consumes one level; the path parser receives a\.b json.GetInt(data, "/a.b") // 1 — under Pointer mode the dot is part of the key name, simpler json.GetInt(data, "/c[0]") // 2 ``` Note that Pointer and dot syntax cannot be mixed; Pointer mode does not support negative indices, and `Set` via Pointer cannot write out of range. See [Path Escaping](../getting-started/path-syntax#path-escaping) and [JSON Pointer](../getting-started/path-syntax#json-pointer-rfc-6901). ## How much code do I need to change to migrate from the standard library? **Answer:** Usually just swap the import path: `"encoding/json"` → `"github.com/cybergodev/json"`, and existing code compiles and runs. `Marshal`/`Unmarshal`/`Compact` and other functions, `Encoder`/`Decoder` methods, and error types (`SyntaxError`, `UnmarshalTypeError`, etc.) are compatible one-to-one; the extra `cfg ...Config` parameters are all optional. What to watch for are the few boundary differences introduced by default input security validation (see the next question). For the migration steps and compatibility list, see [Migrating from the Standard Library](../getting-started/migration). ## Why did Unmarshal reject data containing onload or eval(? **Answer:** That is the default input validation intercepting injection patterns: 28 built-in dangerous patterns (`