partialmarshal

README

PartialMarshal

A Go library for JSON marshaling with extra payloads.

Standard Go JSON marshaling into a struct discards any unmatching fields from the JSON payload. In some use cases, the developer does not want to discard this extra payload data. This library provides a familiar interface for performing marshaling and unmarshaling while keeping any extra data for use by the calling code.

Install

go get github.com/mrhwick/partialmarshal

Usage and Examples

Just like the standard library json package, partialmarshal provides a simple pair of functions for marshaling and unmarshaling of JSON-formatted data into and out of structs.

When a user wants to use partialmarshal to hold onto extra data from a JSON payload, they may simply add the partialmarshal.Extra type as an embedded type in their struct. This embedded type is used by the partialmarshal library for storage of any data from the provided JSON that doesn't match a field of that struct.

type Person struct {
	Name string
	FavoriteFood string `json:"favorite_food"`
	partialmarshal.Extra
}

jsonData := []bytes(`{"name": "gopher", "favorite_food": "Pizza", "age": 25}`)

// Unmarshaling
// => Person{Name: "gopher", FavoriteFood: "Pizza", partialmarshal.Extra{"age":25}}
var p Person
partialmarshal.Unmarshal(jsonData, &p)

// Marshaling
// => `{"name": "gopher", "favorite_food": "Salad", "age" 25}`
p.FavoriteFood = "Salad"
result, err := partialmarshal.Marshal(p)

Documentation

Overview

Package partialmarshal provides JSON marshaling with support for extra/unmatching payload storage.

Index

• func Marshal(v interface{}) ([]byte, error)
• func Unmarshal(data []byte, v interface{}) error
• type Extra

Examples

• Marshal
• Unmarshal

Functions

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal returns the JSON encoding of v.

This inmplementation of Marshal also detects the existence of the partialmarshal.Extra type as an embedded type in v and places the extra payload into the JSON output as top-level key/value pairs.

Example

// A struct type with partialmarshal.Extra included as an embedded type
type examplestruct struct {
	ExampleFieldOne string
	ExampleFieldTwo string `json:"example_field_two"`
	Extra
}

// An instance of that type
source := examplestruct{
	"Value 1",
	"Value 2",
	Extra{
		"some_other_field": []byte(`"some other value"`),
	},
}

// Marshaling into JSON-formatted string.
JSONData, _ := Marshal(source)
fmt.Println(string(JSONData))

Output:
{"ExampleFieldOne":"Value 1","example_field_two":"Value 2","some_other_field":"some other value"}

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v.

This implementation of Unmarshal also detects the existence of the partialmarshal.Extra type as an embedded type in v and places any unmatching data into the embedded Extra map.

Example

// A JSON-formatted string
JSONData := []byte(`{
		"ExampleFieldOne": "value 1",
		"example_field_two": "value 2",
		"some_other_field": "some other value"
	}`)

// A struct type with partialmarshal.Extra included as an embedded type
type StructWithExtra struct {
	ExampleFieldOne string
	ExampleFieldTwo string `json:"example_field_two"`
	Extra
}

// A struct type without partialmarshal.Extra included as an embedded type
type StructWithoutExtra struct {
	ExampleFieldOne string
	ExampleFieldTwo string `json:"example_field_two"`
}

fmt.Println("Nominal Case:")
var destination StructWithExtra
err := Unmarshal(JSONData, &destination)
fmt.Println(err)
fmt.Println(destination.ExampleFieldOne)
fmt.Println(destination.ExampleFieldTwo)
fmt.Printf("%s", destination.Extra["some_other_field"])

Output:
Nominal Case:
<nil>
value 1
value 2
"some other value"

Types

type Extra

type Extra map[string]json.RawMessage

Extra - A type provided for use as an embedded type to indicate a storage location for extra payloads when unmarshaling.