# ghodss/yaml architecture

> Architecture diagram of the GitHub repository ghodss/yaml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghodss/yaml
- Repository: https://github.com/ghodss/yaml

## Overview

ghodss/yaml is a small Go library that adapts YAML and Go values through JSON, so Go’s JSON struct tags and custom JSON methods apply. The main workflow is marshaling a Go value to YAML or unmarshaling YAML into a Go value; callers can also convert YAML and JSON directly, with strict variants. YAML-to-JSON conversion normalizes YAML values and map keys, using field metadata to match struct targets. The graph follows README-described behavior and shown source excerpts; unsampled implementation details are not expanded.

Main entry points: [`yaml.go`](https://github.com/ghodss/yaml/blob/master/yaml.go) (YAML to JSON), [`fields.go`](https://github.com/ghodss/yaml/blob/master/fields.go) (JSON field mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_marshal["Marshal<br/>[yaml.go]"]
  node_unmarshal["Unmarshal<br/>[yaml.go]"]
  node_direct["Direct converters<br/>[yaml.go]"]
end

subgraph group_conversion["Conversion internals"]
  node_yamljson["YAML to JSON<br/>[yaml.go]"]
  node_jsonyaml["JSON to YAML<br/>[yaml.go]"]
  node_normalize["YAML normalization<br/>[yaml.go]"]
  node_fieldmap["JSON field mapping<br/>[fields.go]"]
end

node_caller(("Go caller"))
node_gojson["Go JSON package"]
node_goyaml["go-yaml package"]

node_caller -->|"calls"| node_marshal
node_caller -->|"calls"| node_unmarshal
node_caller -->|"calls"| node_direct
node_marshal -->|"converts via"| node_jsonyaml
node_marshal -->|"marshals with"| node_gojson
node_unmarshal -->|"converts via"| node_yamljson
node_unmarshal -->|"decodes with"| node_gojson
node_yamljson -->|"parses with"| node_goyaml
node_yamljson -->|"normalizes through"| node_normalize
node_normalize -->|"looks up fields"| node_fieldmap
node_jsonyaml -->|"decodes with"| node_gojson
node_jsonyaml -->|"encodes with"| node_goyaml
node_direct -->|"converts through"| node_yamljson
node_direct -->|"converts through"| node_jsonyaml

click node_marshal "https://github.com/ghodss/yaml/blob/master/yaml.go"
click node_unmarshal "https://github.com/ghodss/yaml/blob/master/yaml.go"
click node_direct "https://github.com/ghodss/yaml/blob/master/yaml.go"
click node_yamljson "https://github.com/ghodss/yaml/blob/master/yaml.go"
click node_jsonyaml "https://github.com/ghodss/yaml/blob/master/yaml.go"
click node_normalize "https://github.com/ghodss/yaml/blob/master/yaml.go"
click node_fieldmap "https://github.com/ghodss/yaml/blob/master/fields.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_marshal,node_unmarshal,node_direct toneBlue
class node_yamljson,node_jsonyaml,node_normalize,node_fieldmap toneAmber
class node_caller,node_gojson,node_goyaml toneIndigo
```

## Components

### Public API

- [Marshal](https://github.com/ghodss/yaml/blob/master/yaml.go): `yaml.go`
- [Unmarshal](https://github.com/ghodss/yaml/blob/master/yaml.go): `yaml.go`
- [Direct converters](https://github.com/ghodss/yaml/blob/master/yaml.go): `yaml.go`

### Conversion internals

- [YAML to JSON](https://github.com/ghodss/yaml/blob/master/yaml.go): `yaml.go`
- [JSON to YAML](https://github.com/ghodss/yaml/blob/master/yaml.go): `yaml.go`
- [YAML normalization](https://github.com/ghodss/yaml/blob/master/yaml.go): `yaml.go`
- [JSON field mapping](https://github.com/ghodss/yaml/blob/master/fields.go): `fields.go`

### Other components

- **Go caller**
- **Go JSON package**
- **go-yaml package**

## Connections

- Go caller → Marshal: calls (evidence: `README.md`)
- Go caller → Unmarshal: calls (evidence: `README.md`)
- Go caller → Direct converters: calls (evidence: `README.md`)
- Marshal → JSON to YAML: converts via (evidence: `yaml.go`)
- Marshal → Go JSON package: marshals with (evidence: `README.md`)
- Unmarshal → YAML to JSON: converts via (evidence: `yaml.go`)
- Unmarshal → Go JSON package: decodes with (evidence: `yaml.go`)
- YAML to JSON → go-yaml package: parses with (evidence: `yaml.go`)
- YAML to JSON → YAML normalization: normalizes through (evidence: `yaml.go`)
- YAML normalization → JSON field mapping: looks up fields (evidence: `yaml.go`)
- JSON to YAML → Go JSON package: decodes with (evidence: `yaml.go`)
- JSON to YAML → go-yaml package: encodes with (evidence: `yaml.go`)
- Direct converters → YAML to JSON: converts through (evidence: `README.md`)
- Direct converters → JSON to YAML: converts through (evidence: `README.md`)
