1# YAML marshaling and unmarshaling support for Go 2 3[![Build Status](https://travis-ci.org/ghodss/yaml.svg)](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