README
¶
YAML marshaling and unmarshaling support for Go
kubernetes-sigs/yaml is a permanent fork of ghodss/yaml.
Introduction
A wrapper around go-yaml designed to enable a better way of handling YAML when marshaling to and from structs.
In short, this library first converts YAML to JSON using go-yaml and then uses json.Marshal and json.Unmarshal to convert to or from the struct. This means that it effectively reuses the JSON struct tags as well as the custom JSON methods MarshalJSON and UnmarshalJSON unlike go-yaml. For a detailed overview of the rationale behind this method, see this blog post.
Compatibility
This package uses go-yaml and therefore supports everything go-yaml supports.
Caveats
Caveat #1: When using yaml.Marshal and yaml.Unmarshal, binary data should NOT be preceded with the !!binary YAML tag. If you do, go-yaml will convert the binary data from base64 to native binary data, which is not compatible with JSON. You can still use binary in your YAML files though - just store them without the !!binary tag and decode the base64 in your code (e.g. in the custom JSON methods MarshalJSON and UnmarshalJSON). This also has the benefit that your YAML and your JSON binary data will be decoded exactly the same way. As an example:
BAD:
exampleKey: !!binary gIGC
GOOD:
exampleKey: gIGC
... and decode the base64 data in your code.
Caveat #2: When using YAMLToJSON directly, maps with keys that are maps will result in an error since this is not supported by JSON. This error will occur in Unmarshal as well since you can't unmarshal map keys anyways since struct fields can't be keys.
Installation and usage
To install, run:
$ go get github.com/Intellection/kubernetes-sigs-yaml
And import using:
import "github.com/Intellection/kubernetes-sigs-yaml"
Usage is very similar to the JSON library:
package main
import (
"fmt"
"github.com/Intellection/kubernetes-sigs-yaml"
)
type Person struct {
Name string `json:"name"` // Affects YAML field names too.
Age int `json:"age"`
}
func main() {
// Marshal a Person struct to YAML.
p := Person{"John", 30}
y, err := yaml.Marshal(p)
if err != nil {
fmt.Printf("err: %v\n", err)
return
}
fmt.Println(string(y))
/* Output:
age: 30
name: John
*/
// Unmarshal the YAML back into a Person struct.
var p2 Person
err = yaml.Unmarshal(y, &p2)
if err != nil {
fmt.Printf("err: %v\n", err)
return
}
fmt.Println(p2)
/* Output:
{John 30}
*/
}
yaml.YAMLToJSON and yaml.JSONToYAML methods are also available:
package main
import (
"fmt"
"github.com/Intellection/kubernetes-sigs-yaml"
)
func main() {
j := []byte(`{"name": "John", "age": 30}`)
y, err := yaml.JSONToYAML(j)
if err != nil {
fmt.Printf("err: %v\n", err)
return
}
fmt.Println(string(y))
/* Output:
age: 30
name: John
*/
j2, err := yaml.YAMLToJSON(y)
if err != nil {
fmt.Printf("err: %v\n", err)
return
}
fmt.Println(string(j2))
/* Output:
{"age":30,"name":"John"}
*/
}
Documentation
¶
Index ¶
- func DisallowUnknownFields(d *json.Decoder) *json.Decoder
- func JSONObjectToYAMLObject(j map[string]interface{}) yaml.MapSlice
- func JSONToYAML(j []byte) ([]byte, error)
- func Marshal(obj interface{}) ([]byte, error)
- func Unmarshal(yamlBytes []byte, obj interface{}, opts ...JSONOpt) error
- func UnmarshalStrict(yamlBytes []byte, obj interface{}, opts ...JSONOpt) error
- func YAMLToJSON(y []byte) ([]byte, error)
- func YAMLToJSONStrict(y []byte) ([]byte, error)
- type JSONOpt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DisallowUnknownFields ¶
DisallowUnknownFields configures the JSON decoder to error out if unknown fields come along, instead of dropping them by default.
func JSONObjectToYAMLObject ¶
JSONObjectToYAMLObject converts an in-memory JSON object into a YAML in-memory MapSlice, without going through a byte representation. A nil or empty map[string]interface{} input is converted to an empty map, i.e. yaml.MapSlice(nil).
interface{} slices stay interface{} slices. map[string]interface{} becomes yaml.MapSlice.
int64 and float64 are down casted following the logic of github.com/go-yaml/yaml: - float64s are down-casted as far as possible without data-loss to int, int64, uint64. - int64s are down-casted to int if possible without data-loss.
Big int/int64/uint64 do not lose precision as in the json-yaml roundtripping case.
string, bool and any other types are unchanged.
func JSONToYAML ¶
JSONToYAML converts JSON to YAML. Notable implementation details:
- Duplicate fields, are case-sensitively ignored in an undefined order.
- The sequence indentation style is compact, which means that the "- " marker for a YAML sequence will be on the same indentation level as the sequence field name.
- Unlike Unmarshal, all integers, up to 64 bits, are preserved during this round-trip.
func Marshal ¶
Marshal marshals obj into JSON using stdlib json.Marshal, and then converts JSON to YAML using JSONToYAML (see that method for more reference)
func Unmarshal ¶
Unmarshal first converts the given YAML to JSON, and then unmarshals the JSON into obj. Options for the standard library json.Decoder can be optionally specified, e.g. to decode untyped numbers into json.Number instead of float64, or to disallow unknown fields (but for that purpose, see also UnmarshalStrict). obj must be a non-nil pointer.
Important notes about the Unmarshal logic:
- Decoding is case-insensitive, unlike the rest of Kubernetes API machinery, as this is using the stdlib json library. This might be confusing to users.
- This decodes any number (although it is an integer) into a float64 if the type of obj is unknown, e.g. *map[string]interface{}, *interface{}, or *[]interface{}. This means integers above +/- 2^53 will lose precision when round-tripping. Make a JSONOpt that calls d.UseNumber() to avoid this.
- Duplicate fields, including in-case-sensitive matches, are ignored in an undefined order. Note that the YAML specification forbids duplicate fields, so this logic is more permissive than it needs to. See UnmarshalStrict for an alternative.
- Unknown fields, i.e. serialized data that do not map to a field in obj, are ignored. Use d.DisallowUnknownFields() or UnmarshalStrict to override.
- As per the YAML 1.1 specification, which yaml.v2 used underneath implements, literal 'yes' and 'no' strings without quotation marks will be converted to true/false implicitly.
- YAML non-string keys, e.g. ints, bools and floats, are converted to strings implicitly during the YAML to JSON conversion process.
- There are no compatibility guarantees for returned error values.
func UnmarshalStrict ¶
UnmarshalStrict is similar to Unmarshal (please read its documentation for reference), with the following exceptions:
- Duplicate fields in an object yield an error. This is according to the YAML specification.
- If obj, or any of its recursive children, is a struct, presence of fields in the serialized data unknown to the struct will yield an error.
func YAMLToJSON ¶
YAMLToJSON converts YAML to JSON. Since JSON is a subset of YAML, passing JSON through this method should be a no-op.
Some things YAML can do that are not supported by JSON:
- In YAML you can have binary and null keys in your maps. These are invalid in JSON, and therefore int, bool and float keys are converted to strings implicitly.
- Binary data in YAML with the !!binary tag is not supported. If you want to use binary data with this library, encode the data as base64 as usual but do not use the !!binary tag in your YAML. This will ensure the original base64 encoded data makes it all the way through to the JSON.
- And more... read the YAML specification for more details.
Notable about the implementation:
- Duplicate fields are case-sensitively ignored in an undefined order. Note that the YAML specification forbids duplicate fields, so this logic is more permissive than it needs to. See YAMLToJSONStrict for an alternative. - As per the YAML 1.1 specification, which yaml.v2 used underneath implements, literal 'yes' and 'no' strings without quotation marks will be converted to true/false implicitly. - Unlike Unmarshal, all integers, up to 64 bits, are preserved during this round-trip. - There are no compatibility guarantees for returned error values.
func YAMLToJSONStrict ¶
YAMLToJSONStrict is like YAMLToJSON but enables strict YAML decoding, returning an error on any duplicate field names.
Source Files