README.md
1# YAML marshaling and unmarshaling support for Go
2
3[](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
){kind=link}