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