jsontype

README

jsontype

A JSON type that round-trips correctly between Go, JSON, and SQL drivers — Postgres jsonb, MySQL json, SQLite TEXT, anything that scans to []byte or string.

Zero third-party dependencies.

Install

go get github.com/ubgo/jsontype

Quick start (with Ent or any database/sql ORM)

import "github.com/ubgo/jsontype"

type User struct {
    ID       int             `json:"id"`
    Settings jsontype.JSON   `json:"settings"`
}

// Settings is stored as jsonb / json / TEXT in the DB and scans round-trip
// via sql.Scanner / driver.Valuer.

Quick start (with gqlgen for GraphQL custom scalars)

jsontype.JSON already implements MarshalGQL / UnmarshalGQL. Add a scalar binding in your gqlgen.yml:

models:
  JSON:
    model:
      - github.com/ubgo/jsontype.JSON

Then declare scalar JSON in your schema and use it on any field.

API

Method	Purpose
Value() (driver.Value, error)	database/sql/driver.Valuer. Empty JSON → SQL NULL.
Scan(value any) error	database/sql.Scanner. Accepts []byte, string, nil (→ JSON null literal).
MarshalJSON() ([]byte, error)	Returns raw JSON bytes (no base64 wrapping).
UnmarshalJSON(b []byte) error	Validates input via json.Valid before storing.
MarshalGQL(w io.Writer)	gqlgen Marshaler. Duck-typed; jsontype does not import gqlgen.
UnmarshalGQL(input any) error	Accepts string, []byte, or map[string]any.
From(v any) (*JSON, error)	Marshal an arbitrary value into a *JSON.

Why not json.RawMessage directly?

json.RawMessage doesn't implement sql.Scanner / driver.Valuer, and its UnmarshalJSON doesn't validate input — so db.Scan(...) and json.Unmarshal(invalidBytes, &raw) both fail in surprising ways. jsontype.JSON covers both gaps without leaving the standard library.

License

Apache License 2.0. See LICENSE.

Documentation

Overview

Package jsontype provides a JSON wrapper type that round-trips correctly between Go, JSON, and SQL drivers (Postgres jsonb, MySQL json, SQLite TEXT).

JSON is a thin alias over json.RawMessage that implements:

• sql.Scanner / driver.Valuer for database round-tripping
• json.Marshaler / json.Unmarshaler so it serialises as raw JSON instead of the base64-encoded []byte the default would produce
• MarshalGQL / UnmarshalGQL for gqlgen scalar adapters (the methods are duck-typed; jsontype itself does not import gqlgen)

Index

• type JSON
  • func From(v any) (*JSON, error)
  • func (j JSON) MarshalGQL(w io.Writer)
  • func (j JSON) MarshalJSON() ([]byte, error)
  • func (j *JSON) Scan(value any) error
  • func (j *JSON) UnmarshalGQL(input any) error
  • func (j *JSON) UnmarshalJSON(b []byte) error
  • func (j JSON) Value() (driver.Value, error)

Types

type JSON

type JSON json.RawMessage

JSON is a json.RawMessage that round-trips through SQL drivers and gqlgen.

func From

func From(v any) (*JSON, error)

From marshals an arbitrary value into a *JSON. Convenient for passing arbitrary structures into a database column without manual marshalling.

func (JSON) MarshalGQL

func (j JSON) MarshalGQL(w io.Writer)

MarshalGQL writes the JSON bytes to w. Implements the gqlgen Marshaler interface (duck-typed; this package does not import gqlgen).

func (JSON) MarshalJSON

func (j JSON) MarshalJSON() ([]byte, error)

MarshalJSON returns the raw JSON bytes without base64 encoding.

func (*JSON) Scan

func (j *JSON) Scan(value any) error

Scan implements database/sql.Scanner. It accepts []byte, string, or nil (mapped to the JSON null literal).

func (*JSON) UnmarshalGQL

func (j *JSON) UnmarshalGQL(input any) error

UnmarshalGQL parses an input from gqlgen — string, []byte, or map[string]any — into JSON.

func (*JSON) UnmarshalJSON

func (j *JSON) UnmarshalJSON(b []byte) error

UnmarshalJSON deserialises raw JSON bytes into JSON. Returns an error if the input is not valid JSON (json.RawMessage.UnmarshalJSON does not validate, so we wrap json.Valid for safer round-tripping).

func (JSON) Value

func (j JSON) Value() (driver.Value, error)

Value implements database/sql/driver.Valuer.

An empty JSON returns nil so it lands in the database as SQL NULL rather than the literal text "null".