Skip to content

Migrating from the Standard Library ​

cybergodev/json shares the function signatures of the standard encoding/json: after replacing the import path, existing code compiles as-is. There is one deliberate semantic difference — this library validates input by default, rejecting oversized data or data containing dangerous patterns, where the standard library accepts everything (see Behavioral Differences). This page covers the three-step migration, the API mapping tables, and the incremental capabilities.

Migration in Three Steps ​

  1. Install:

    bash
    go get github.com/cybergodev/json
  2. Replace the import: change "encoding/json" to "github.com/cybergodev/json".

    go
    // Before migration
    import "encoding/json"
    
    // After migration
    import "github.com/cybergodev/json"
  3. Compile: signatures match, so code compiles; if the input contains words such as onload or eval(, or exceeds 100MB, default validation rejects it at run time — see the migration FAQ.

Signature-Compatible APIs ​

The table maps encoding/json to cybergodev/json. Entries marked signature-compatible can be swapped at the signature level; behavioral differences from default input validation are collected in Behavioral Differences:

encoding/jsoncybergodev/jsonNotes
Marshal(v)Marshal(v, cfg...)Signature-compatible with an extra optional cfg; output above MaxJSONSize returns ErrSizeLimit
Unmarshal(data, &v)Unmarshal(data, &v, cfg...)Signature-compatible; input is security-validated by default
MarshalIndent(v, prefix, indent)Same nameSignature-compatible; byte-identical output to the standard library for typical values
Compact(dst, src)Same nameSignature-compatible; input is security-validated by default
Indent(dst, src, prefix, indent)Same nameSignature-compatible; input is security-validated by default
HTMLEscape(dst, src)Same nameSignature-compatible
Valid(data)Valid(data, cfg...)Signature-compatible; checks size, UTF-8, and dangerous patterns beyond syntax
NewEncoder(w)NewEncoder(w, cfg...)Signature-compatible
NewDecoder(r)NewDecoder(r, cfg...)Signature-compatible
NumberNumberType-compatible (String/Int64/Float64/MarshalJSON all preserved)
DelimDelimType-compatible (String() preserved)
TokenTokenType-compatible

Method-level signatures of Encoder and Decoder map one to one as well:

MethodBelongs toCompatibility
Encode(v) / SetIndent(prefix, indent) / SetEscapeHTML(on)*EncoderSignature-compatible
Decode(v) / Token() / More() / Buffered() / InputOffset()*DecoderSignature-compatible
UseNumber() / DisallowUnknownFields()*DecoderSignature-compatible; DisallowUnknownFields is honored on the default decode path

Error types map one to one as well; code relying on errors.As / type assertions works directly: SyntaxError, UnmarshalTypeError, InvalidUnmarshalError, MarshalerError, UnsupportedTypeError, and UnsupportedValueError all exist with matching types and field layouts (see Error Variables).

The error structs' locator fields are likewise preserved, so code that pinpoints failures or tallies error categories by these fields keeps working:

TypeFieldTypeDescription
SyntaxErrorOffsetint64Bytes read before the error occurred
UnmarshalTypeErrorOffsetint64Bytes read before the error occurred
UnmarshalTypeErrorStructstringName of the root type containing the failing field
UnmarshalTypeErrorFieldstringFull path from the root to the failing value
UnsupportedValueErrorStrstringText representation of the unsupported value (e.g. NaN, +Inf)

When UnmarshalTypeError's Struct / Field are non-empty, Error() prints json: cannot unmarshal <value> into Go struct field <Struct>.<Field> of type <type> — verbatim identical to the standard library.

Optional cfg parameters

Every extra cfg ...Config parameter is optional (variadic). Without it the default configuration applies and most ordinary data yields the same results as the standard library; the only differences come from default input validation (see Behavioral Differences). Pass cfg to enable security mode, caching, and other capabilities.

Three intentional exceptions regarding cfg (from the library's design conventions):

  • Typed read functions (GetTyped, GetString, GetInt, etc.) take default values as their variadic parameter, not cfg — Go allows only one variadic parameter. For configuration-aware typed reads, use SafeGet, or the typed methods (GetString, GetInt) of a Processor created with New(cfg).
  • Flag-preset variants (SetCreate, SetMultipleCreate, DeleteClean) equal the plain versions with CreatePaths (or CleanupNulls + CompactArrays) forcibly enabled.
  • Valid returns a single bool (standard-library signature); use ValidWithConfig (returning bool, error) when you need the failure reason.

Code Example: Change Only the Import ​

The example below shows the import-only swap; encoding, decoding, and struct tag usage stay the same:

go
package main

import (
	"fmt"

	"github.com/cybergodev/json"
)

func main() {
	type User struct {
		Name string   `json:"name"`
		Age  int      `json:"age"`
		Tags []string `json:"tags"`
	}

	// Encode — same signature and same output as encoding/json
	user := User{Name: "Alice", Age: 30, Tags: []string{"go", "json"}}
	b, err := json.Marshal(user)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b))
	// Output: {"name":"Alice","age":30,"tags":["go","json"]}

	// Decode — matches encoding/json when the input passes validation
	var u User
	if err := json.Unmarshal(b, &u); err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", u)
	// Output: {Name:Alice Age:30 Tags:[go json]}
}

Incremental Capabilities ​

After migrating you can adopt these capabilities the standard library lacks while keeping signature compatibility:

CapabilityExampleLearn more
Path queriesjson.GetString(data, "user.name")Path Expression Syntax
Get with defaultsjson.GetInt(data, "timeout", 30)Query & Get
Generic getjson.GetTyped[User](data, "user")Generic Operations
Path modificationjson.Set(data, "user.name", "Bob")Modification Operations
Schema validationjson.ValidateSchema(data, schema)Schema Validation
Streaming JSONLjson.StreamLinesInto[T](r, fn)JSONL Processing
High-performance processorp, _ := json.New()Processor Guide
Pre-parse / pre-compiled pathsp.PreParse / p.CompilePathProcessor Guide
Concurrent iterationjson.NewParallelIterator(items).ForEach(fn)Concurrency
Context cancellationjson.GetWithContext(ctx, data, path)Query & Get
Deep JSON comparisonjson.CompareJSON(a, b)Utility Functions
Hooks / audit / timingp.AddHook(json.LoggingHook(logger))Hook System
Security modejson.SecurityConfig()Security Mode
Runtime stats / healthjson.GetStats() / json.GetHealthStatus()Processor Guide

What Are the Behavioral Differences from the Standard Library? ​

For input that carries no dangerous pattern, stays within limits, and is validly encoded, the default configuration returns the same results as encoding/json. Differences come from input security validation, which is on by default: oversized input or input containing dangerous patterns is rejected, where the standard library accepts everything.

Differenceencoding/jsonCyberGo default behaviorWhen you need different behavior
Input sizeUnlimitedAbove 100MB (MaxJSONSize) returns ErrSizeLimitRaise cfg.MaxJSONSize
Nesting depthNo explicit limitAbove 200 levels (MaxNestingDepthSecurity) returns ErrDepthLimitAdjust MaxNestingDepthSecurity
Dangerous content patternsNot checked28 built-in patterns blocked by default (__proto__, <script, javascript:, eval(, onload, etc.), returning ErrSecurityViolationAfter confirming trust, set cfg.DisableDefaultPatterns = true (the 3 critical patterns such as __proto__ still block)
Container widthUnlimitedPer object ≤ 100k keys, per array ≤ 100k elements (exceeding returns ErrSizeLimit)Adjust MaxObjectKeys / MaxArrayElements
Invalid UTF-8Replaced with U+FFFD at decodeRejected outright (ErrInvalidJSON; Valid returns false)Fix the input encoding beforehand
BOM prefixSyntax errorRejected (ErrInvalidJSON)Strip the BOM in preprocessing
Marshal output capNo capOutput above MaxJSONSize returns ErrSizeLimitRaise cfg.MaxJSONSize
Marshal nesting depthUnlimitedAbove MaxDepth (default 100) returns ErrDepthLimitRaise cfg.MaxDepth, or set 0 for no limit

Two points that are easy to misread:

  1. Finer error types for path operations: a JsonsError from a failed path query or modification carries the operation name, path, and underlying cause (supporting errors.Is/errors.As and Unwrap), but it does not change the error types of standard-library-compatible functions (Unmarshal/Decode, etc.) — those still return standard forms like SyntaxError and UnmarshalTypeError.
  2. Validation scope: content-pattern validation targets JSON text input only (Unmarshal, Get, Parse, Valid, etc.); Marshal/Encode of Go values does no content-pattern validation, but output size (MaxJSONSize) and nesting depth (MaxDepth, default 100) still apply.

For untrusted input, prefer the json.SecurityConfig() preset (tighter limits + full scanning); see Security Mode.

Migration FAQ ​

Q: Does json.Number big-number precision behavior change?

No. Decoder.UseNumber() matches the standard library; Number.Int64()/Float64() behave unchanged. Use json.Number as usual when the original number text must be preserved.

Q: Is the default HTML escaping identical?

Yes. Marshal/Encode escape <, >, & by default (same as the standard library), and Encoder.SetEscapeHTML(false) turns it off. Note that Marshal always escapes even when cfg.EscapeHTML=false; use Encode when the config must be honored.

Q: What about existing code using json.Marshaler/json.Unmarshaler custom types?

Signature-compatible. Both interfaces keep working; custom types implementing them behave the same on the encode/decode paths.

Q: Can I use the incremental capabilities only in new code and leave old code untouched?

Yes. Package-level functions cache the corresponding Processor by trailing cfg (see the cfg conventions above); calls without cfg go through the global processor with the default configuration — results match the standard library whenever the input does not trip validation; see the Behavioral Differences table above.

Q: Unmarshal rejected legitimate data containing words like onload or eval(. What now?

That is the default input validation intercepting injection patterns. After confirming the input is trusted, disable the default pattern set:

go
cfg := json.DefaultConfig()
cfg.DisableDefaultPatterns = true
err := json.Unmarshal(data, &v, cfg)

Note that the three critical patterns __proto__, constructor[, and prototype. are always blocked, unaffected by this switch. To only add rules, append custom patterns via AdditionalDangerousPatterns instead of disabling the defaults.

Q: A document larger than 100MB was rejected with ErrSizeLimit. What should I do?

Two routes: raise cfg.MaxJSONSize if you truly must process it whole; better, switch to streaming (NewStreamIterator / NewStreamObjectIterator for per-element reads, or the JSONL family for line-by-line processing) to avoid loading it all into memory — see Large File Handling.

Next Steps ​