Migrating from the Standard Library

cybergodev/json is 100% compatible with the standard library encoding/json — simply replace the import path and your existing code compiles and runs without any changes. This page walks you through the migration and the additional capabilities you gain.

Migration in Three Steps

1. Install:

   go get github.com/cybergodev/json

2. Replace the import: swap "encoding/json" for "github.com/cybergodev/json".

   // Before
   import "encoding/json"
   
   // After
   import "github.com/cybergodev/json"

3. Done: it compiles, and all your existing code works unchanged.

Fully Compatible API

The table below maps encoding/json to cybergodev/json:

encoding/json	cybergodev/json	Notes
Marshal(v)	Marshal(v, cfg...)	Compatible signature, optional cfg param
Unmarshal(data, &v)	Unmarshal(data, &v, cfg...)	Same as above
MarshalIndent(v, prefix, indent)	Same name	Fully compatible
Compact(dst, src)	Same name	Fully compatible
Indent(dst, src, prefix, indent)	Same name	Fully compatible
HTMLEscape(dst, src)	Same name	Fully compatible
Valid(data)	Valid(data, cfg...)	Compatible signature
NewEncoder(w)	NewEncoder(w, cfg...)	Compatible signature
NewDecoder(r)	NewDecoder(r, cfg...)	Compatible signature
Number	Number	Type compatible
Delim	Delim	Type compatible
Token	Token	Type compatible

Optional cfg parameter

All extra cfg ...Config parameters are optional (variadic). When omitted, behavior is identical to the standard library; pass them only when you want to enable enhanced capabilities such as security mode or caching.

Code Example: Just Swap the Import

The example below shows the "swap the import only" effect — encoding, decoding, and struct tags work exactly as with encoding/json:

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 — exactly the same 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 — exactly the same as encoding/json
    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]}
}

Additional Capabilities

After migrating, while keeping standard-library compatibility, you can opt into the following capabilities that the standard library does not offer:

Capability	Example	Learn more
Path queries	json.GetString(data, "user.name")	Path Expression Syntax
Get with default	json.GetInt(data, "timeout", 30)	Query Functions
Generic get	json.GetTyped[User](data, "user")	Generics
Path modification	json.Set(data, "user.name", "Bob")	Modify Operations
Schema validation	json.ValidateSchema(data, schema)	Validator
Streaming JSONL	json.StreamLinesInto[T](r, fn)	JSONL Processing
High-performance processor	p, _ := json.New()	Processor Guide

Behavioral Differences

Under the default configuration, cybergodev/json behaves identically to encoding/json. All extra capabilities (security mode, path queries, schema validation, etc.) are opt-in — enabled explicitly via the Config parameter, with no impact on existing code.

In other words: migration is zero-cost, and you gain a superset of "standard library + additional capabilities".

Next Steps

• Quick Start — Get going with core features in 5 minutes
• Path Expression Syntax — Learn the path query syntax
• Cheat Sheet — Quick API reference