1# YAML marshaling and unmarshaling support for Go 2 3[![Build Status](https://travis-ci.org/kubernetes-sigs/yaml.svg)](https://travis-ci.org/kubernetes-sigs/yaml) 4 5kubernetes-sigs/yaml is a permanent fork of [ghodss/yaml](https://github.com/ghodss/yaml). 6 7## Introduction 8 9A wrapper around [go-yaml](https://github.com/go-yaml/yaml) designed to enable a better way of handling YAML when marshaling to and from structs. 10 11In 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](http://web.archive.org/web/20190603050330/http://ghodss.com/2014/the-right-way-to-handle-yaml-in-golang/). 12 13## Compatibility 14 15This package uses [go-yaml](https://github.com/go-yaml/yaml) and therefore supports [everything go-yaml supports](https://github.com/go-yaml/yaml#compatibility). 16 17## Caveats 18 19**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: 20 21``` 22BAD: 23 exampleKey: !!binary gIGC 24 25GOOD: 26 exampleKey: gIGC 27... and decode the base64 data in your code. 28``` 29 30**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. 31 32## Installation and usage 33 34To install, run: 35 36``` 37$ go get sigs.k8s.io/yaml 38``` 39 40And import using: 41 42``` 43import "sigs.k8s.io/yaml" 44``` 45 46Usage is very similar to the JSON library: 47 48```go 49package main 50 51import ( 52 "fmt" 53 54 "sigs.k8s.io/yaml" 55) 56 57type Person struct { 58 Name string `json:"name"` // Affects YAML field names too. 59 Age int `json:"age"` 60} 61 62func main() { 63 // Marshal a Person struct to YAML. 64 p := Person{"John", 30} 65 y, err := yaml.Marshal(p) 66 if err != nil { 67 fmt.Printf("err: %v\n", err) 68 return 69 } 70 fmt.Println(string(y)) 71 /* Output: 72 age: 30 73 name: John 74 */ 75 76 // Unmarshal the YAML back into a Person struct. 77 var p2 Person 78 err = yaml.Unmarshal(y, &p2) 79 if err != nil { 80 fmt.Printf("err: %v\n", err) 81 return 82 } 83 fmt.Println(p2) 84 /* Output: 85 {John 30} 86 */ 87} 88``` 89 90`yaml.YAMLToJSON` and `yaml.JSONToYAML` methods are also available: 91 92```go 93package main 94 95import ( 96 "fmt" 97 98 "sigs.k8s.io/yaml" 99) 100 101func main() { 102 j := []byte(`{"name": "John", "age": 30}`) 103 y, err := yaml.JSONToYAML(j) 104 if err != nil { 105 fmt.Printf("err: %v\n", err) 106 return 107 } 108 fmt.Println(string(y)) 109 /* Output: 110 name: John 111 age: 30 112 */ 113 j2, err := yaml.YAMLToJSON(y) 114 if err != nil { 115 fmt.Printf("err: %v\n", err) 116 return 117 } 118 fmt.Println(string(j2)) 119 /* Output: 120 {"age":30,"name":"John"} 121 */ 122} 123``` 124