json

Documentation

Overview

Package json provides functions for serializing cty types and values in JSON format, and for decoding them again.

Since the cty type system is a superset of the JSON type system, round-tripping through JSON is lossy unless type information is provided both at encoding time and decoding time. Callers of this package are therefore suggested to define their expected structure as a cty.Type and pass it in consistently both when encoding and when decoding, though default (type-lossy) behavior is provided for situations where the precise representation of the data is not significant.

Index

• func ImpliedType(buf []byte) (cty.Type, error)
• func Marshal(val cty.Value, t cty.Type) ([]byte, error)
• func MarshalType(t cty.Type) ([]byte, error)
• func Unmarshal(buf []byte, t cty.Type) (cty.Value, error)
• func UnmarshalType(buf []byte) (cty.Type, error)
• type SimpleJSONValue
  • func (v SimpleJSONValue) MarshalJSON() ([]byte, error)
  • func (v *SimpleJSONValue) UnmarshalJSON(buf []byte) error

Functions

func ImpliedType

func ImpliedType(buf []byte) (cty.Type, error)

ImpliedType returns the cty Type implied by the structure of the given JSON-compliant buffer. This function implements the default type mapping behavior used when decoding arbitrary JSON without explicit cty Type information.

The rules are as follows:

JSON strings, numbers and bools map to their equivalent primitive type in cty.

JSON objects map to cty object types, with the attributes defined by the object keys and the types of their values.

JSON arrays map to cty tuple types, with the elements defined by the types of the array members.

Any nulls are typed as DynamicPseudoType, so callers of this function must be prepared to deal with this. Callers that do not wish to deal with dynamic typing should not use this function and should instead describe their required types explicitly with a cty.Type instance when decoding.

Any JSON syntax errors will be returned as an error, and the type will be the invalid value cty.NilType.

func Marshal

func Marshal(val cty.Value, t cty.Type) ([]byte, error)

Marshal produces a JSON representation of the given value that can later be decoded into a value of the given type.

A type is specified separately to allow for the given type to include cty.DynamicPseudoType to represent situations where any type is permitted and so type information must be included to allow recovery of the stored structure when decoding.

The given type will also be used to attempt automatic conversions of any non-conformant types in the given value, although this will not always be possible. If the value cannot be made to be conformant then an error is returned, which may be a cty.PathError.

Capsule-typed values can be marshalled, but with some caveats. Since capsule values are compared by pointer equality, it is impossible to recover a value that will compare equal to the original value. Additionally, it's not possible to JSON-serialize the capsule type itself, so it's not valid to use capsule types within parts of the value that are conformed to cty.DynamicPseudoType. Otherwise, a capsule value can be used as long as the encapsulated type itself is serializable with the Marshal function in encoding/json.

func MarshalType

func MarshalType(t cty.Type) ([]byte, error)

MarshalType returns a JSON serialization of the given type.

This is just a thin wrapper around t.MarshalJSON, for symmetry with UnmarshalType.

func Unmarshal

func Unmarshal(buf []byte, t cty.Type) (cty.Value, error)

Unmarshal decodes a JSON representation of the given value into a cty Value conforming to the given type.

While decoding, type conversions will be done where possible to make the result conformant even if the types given in JSON are not exactly correct. If conversion isn't possible then an error is returned, which may be a cty.PathError.

func UnmarshalType

func UnmarshalType(buf []byte) (cty.Type, error)

UnmarshalType decodes a JSON serialization of the given type as produced by either Type.MarshalJSON or MarshalType.

This is a convenience wrapper around Type.UnmarshalJSON.

Types

type SimpleJSONValue

type SimpleJSONValue struct {
	cty.Value
}

SimpleJSONValue is a wrapper around cty.Value that adds implementations of json.Marshaler and json.Unmarshaler for simple-but-type-lossy automatic encoding and decoding of values.

The couplet Marshal and Unmarshal both take extra type information to inform the encoding and decoding process so that all of the cty types can be represented even though JSON's type system is a subset.

SimpleJSONValue instead takes the approach of discarding the value's type information and then deriving a new type from the stored structure when decoding. This results in the same data being returned but not necessarily with exactly the same type.

For information on how types are inferred when decoding, see the documentation of the function ImpliedType.

func (SimpleJSONValue) MarshalJSON

func (v SimpleJSONValue) MarshalJSON() ([]byte, error)

MarshalJSON is an implementation of json.Marshaler. See the documentation of SimpleJSONValue for more information.

func (*SimpleJSONValue) UnmarshalJSON

func (v *SimpleJSONValue) UnmarshalJSON(buf []byte) error

UnmarshalJSON is an implementation of json.Unmarshaler. See the documentation of SimpleJSONValue for more information.