json

JSON Naming Convention Wrapper

This package provides JSON marshal/unmarshal functions that use custom naming conventions (kebab-case or snake_case) for struct fields by default, while respecting explicit json: tags.

Features

• Automatic kebab-case or snake_case conversion: Struct fields without explicit json: tags are automatically converted
• Tag precedence: Explicit json: tags are always respected
• Recursive transformation: Works with nested structs, slices, and maps
• Indent variants: Support for both compact and indented JSON output
• Thread-safe: Safe for concurrent use (no mutable state)
• File I/O helpers: Convenience functions for reading/writing JSON files
• Standard behavior: Inline with encoding/json (supports omitempty, string tags, etc.)

Installation

go get codeberg.org/basvanbeek/run/pkg/json

Usage

Using Kebab-case

package main

import (
    "fmt"
    "codeberg.org/basvanbeek/run/pkg/json"
)

type Config struct {
    ServerName string  // Will be marshaled as "server-name"
    ListenPort int     // Will be marshaled as "listen-port"
    EnableTLS  bool    // Will be marshaled as "enable-tls"
}

func main() {
    cfg := Config{
        ServerName: "my-server",
        ListenPort: 8080,
        EnableTLS:  true,
    }

    // Marshal to JSON with kebab-case (compact)
    data, err := json.MarshalKebab(cfg)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
    // Output: {"server-name":"my-server","listen-port":8080,"enable-tls":true}

    // Marshal with indentation
    data, err = json.MarshalKebabIndent(cfg, "", "  ")
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
    // Output:
    // {
    //   "server-name": "my-server",
    //   "listen-port": 8080,
    //   "enable-tls": true
    // }

    // Unmarshal from JSON with kebab-case
    var loaded Config
    err = json.UnmarshalKebab(data, &loaded)
    if err != nil {
        panic(err)
    }
}

Using Snake_case

The same functionality is available with snake_case naming:

package main

import (
    "fmt"
    "codeberg.org/basvanbeek/run/pkg/json"
)

type Config struct {
    ServerName string  // Will be marshaled as "server_name"
    ListenPort int     // Will be marshaled as "listen_port"
    EnableTLS  bool    // Will be marshaled as "enable_tls"
}

func main() {
    cfg := Config{
        ServerName: "my-server",
        ListenPort: 8080,
        EnableTLS:  true,
    }

    // Marshal to JSON with snake_case (compact)
    data, err := json.MarshalSnake(cfg)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
    // Output: {"server_name":"my-server","listen_port":8080,"enable_tls":true}

    // Marshal with indentation
    data, err = json.MarshalSnakeIndent(cfg, "", "  ")
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
    // Output:
    // {
    //   "server_name": "my-server",
    //   "listen_port": 8080,
    //   "enable_tls": true
    // }

    // Unmarshal from JSON with snake_case
    var loaded Config
    err = json.UnmarshalSnake(data, &loaded)
    if err != nil {
        panic(err)
    }
}

Using Explicit Tags

Fields with explicit json: tags will use the tag value instead of automatic conversion:

type Config struct {
    ServerName string `json:"custom_server_name"`  // Uses "custom_server_name"
    ListenPort int                                  // Uses "listen-port" (kebab) or "listen_port" (snake)
    EnableTLS  bool   `json:"tls_enabled"`         // Uses "tls_enabled"
}

Nested Structs

The wrapper recursively transforms nested structs:

type AppConfig struct {
    ServerSettings ServerSettings  // Will be "server-settings" or "server_settings"
    DatabaseConfig DatabaseConfig  // Will be "database-config" or "database_config"
}

type ServerSettings struct {
    HostName   string  // Will be "host-name" or "host_name"
    ListenPort int     // Will be "listen-port" or "listen_port"
}

type DatabaseConfig struct {
    ConnectionString string           // Will be "connection-string" or "connection_string"
    MaxConnections   int `json:"max_conn"`  // Uses explicit tag "max_conn"
}

File I/O

File operations automatically use indented output (2-space indent) for readability:

// Write to file (indented)
cfg := Config{ServerName: "test", ListenPort: 8080}
err := json.MarshalKebabToFile("config.json", cfg)

// Read from file
var loaded Config
err = json.UnmarshalKebabFromFile("config.json", &loaded)

// Snake_case variants
err = json.MarshalSnakeToFile("config.json", cfg)
err = json.UnmarshalSnakeFromFile("config.json", &loaded)

Embedded Structs

Exported embedded struct fields are processed normally:

type BaseConfig struct {
    ServerName string
}

type AppConfig struct {
    BaseConfig  // Fields will be inlined
    ExtraField  string
}

Ignoring Fields

Use json:"-" to ignore fields:

type Config struct {
    VisibleField string
    IgnoredField string `json:"-"`  // Will not be marshaled
}

API Reference

Kebab-case Functions

• MarshalKebab(v interface{}) ([]byte, error)
  Marshals v to compact JSON using kebab-case for field names without explicit tags.

• MarshalKebabIndent(v interface{}, prefix, indent string) ([]byte, error)
  Marshals v to indented JSON using kebab-case for field names without explicit tags.

• UnmarshalKebab(data []byte, v interface{}) error
  Unmarshals JSON data into v, expecting kebab-case field names for fields without explicit tags.

• MarshalKebabToFile(filename string, v interface{}) error
  Marshals v to a JSON file using kebab-case naming convention (always indented with 2 spaces).

• UnmarshalKebabFromFile(filename string, v interface{}) error
  Unmarshals JSON from a file into v using kebab-case naming convention.

Snake_case Functions

• MarshalSnake(v interface{}) ([]byte, error)
  Marshals v to compact JSON using snake_case for field names without explicit tags.

• MarshalSnakeIndent(v interface{}, prefix, indent string) ([]byte, error)
  Marshals v to indented JSON using snake_case for field names without explicit tags.

• UnmarshalSnake(data []byte, v interface{}) error
  Unmarshals JSON data into v, expecting snake_case field names for fields without explicit tags.

• MarshalSnakeToFile(filename string, v interface{}) error
  Marshals v to a JSON file using snake_case naming convention (always indented with 2 spaces).

• UnmarshalSnakeFromFile(filename string, v interface{}) error
  Unmarshals JSON from a file into v using snake_case naming convention.

Behavior

Naming Conventions

Kebab-case conversion:

• ServerName → server-name
• ListenPort → listen-port
• TLSEnabled → tls-enabled
• HTTPServer → http-server
• MaxHTTPConnections → max-http-connections

Snake_case conversion:

• ServerName → server_name
• ListenPort → listen_port
• TLSEnabled → tls_enabled
• HTTPServer → http_server
• MaxHTTPConnections → max_http_connections

Field Processing

1. Unexported fields: Skipped (standard Go behavior)
2. Exported fields without tags: Converted to kebab-case or snake_case (depending on which function is used)
3. Exported fields with json: tags: Use the tag value
4. Embedded structs: Inlined at the parent level (standard JSON behavior)
5. Fields with json:"-": Ignored

JSON Tag Options

All standard encoding/json tag options are supported:

• json:"name" - Custom field name
• json:"name,omitempty" - Omit if empty
• json:"name,string" - Marshal number/bool as string
• json:"-" - Skip field

Type Support

The wrapper supports all standard Go types:

• Basic types: string, int, bool, float64, etc.
• Structs (including nested)
• Slices and arrays
• Maps
• Pointers

Output Format

• Compact functions (MarshalKebab, MarshalSnake): No whitespace, minimal size
• Indent functions (MarshalKebabIndent, MarshalSnakeIndent): Custom indentation
• File functions (MarshalKebabToFile, MarshalSnakeToFile): Always indented with 2 spaces for readability

Thread Safety

This package is thread-safe for concurrent marshal/unmarshal operations, as it uses no mutable state and relies on the thread-safe encoding/json library.

License

Copyright (c) 2026 Bas van Beek. Licensed under the Apache License Version 2.0.