godotyaml

README

godotyaml

schema_version = 0

go.yaml is the centralized file for the metadata and configuration of Go projects, filling the gaps of go.mod

This repo provides:

• The spec and standard of go.yaml file. This is the main focus of this README file.
• A small utility library for parsing go.yaml files to be used by other applications. Usage of this library is completely optional.

Philosophy

• go.yaml is not a replacement for go.mod and is only used for metadata/configuration that is not natively supported by official go toolchain.
• There is no overlap between go.yaml and official go tooling (including go.mod) and no such overlap is planned for the future. It means that metadata such as Go version, dependency list, and module name will remain in go.mod
• go.yaml will/can contain both project-level metadata and settings and external tool/library/package configurations.
• No tool/library/package will be treated as first-class citizen with special privileges with the exception of official Go toolchain.
• go.yaml can be validated but an invalid go.yaml will not prevent your Go code from compiling and running.

Anatomy of go.yaml

Sections

A go.yaml file has broadly two sections:

1. Standardized structures (the fields and values the schema defines)
2. Arbitrary configuration for external tools/packages/libraries which can be placed inside go.yaml instead of a standalone file. These arbitrary configurations can only be placed under external key

Root reservation

Please note: All keys at the root level are designed by the schema as an standard and arbitrary data should not be placed at the root level. An external tool/package/library can place their config, without limitation, in external object.

Version

go.yaml provides a version for the project. This version is useful for human-readability and accessing it in your application by embedding go.yaml. This version, however, is not a replacement for VCS tag versions and VCS tag versions remain authoritative.

Usage of external

The external object is only used for configs of the tools and each tool should only define their own configuration and should avoid defining category level configs.

For example, a linter (named myLinter for example), should not use external.linter for their config but they should use external.myLinter. Another linter can define another config under external.secondLinter.

If a category of external tools (such as linters, builders, releasers, etc.) use overlapping configurations, validated by community feedback, we will then promote those overlapping those configs to the schema's root. So, using generic configs such as external.linter, external.build, etc. is highly discouraged.

Spec of go.yaml

go.yaml can be validated but all fields are inherently optional.

name: myproject # The name of the project (not the module name)
description: A useful tool # Optional human-readable description of your project
version: 1.26.3 # The version of your project
schema_version: 0 # The version of schema
repository: https://... # The URL of the repository of the project
issue_tracker: https://... # The URL of the issue tracker of the project
homepage: https://... # Optional URL of the project's homepage/website
documentation: https://... # Optional URL of the project's documentation
license: MIT # The license of the project

# The list of authors
# Each author has a required field of `name` and all other fields are optional. You can add no authors or add multiple authors
authors: 
  - name: Jane Doe
    email: jane@example.com
    organization: Vieolo
    url: example.com
  - name: John Smith
  
  
# The map of executable entry points of the project. A project can have multiple entry points to produce executables. The name of the executable (e.g., server, admin, etc.) is the arbitrary nickname you have for the entry point, the `entrypoint` is required and other fields are optional. A library with no executable, naturally, can skip this field entirely
executables:
  server:
    entrypoint: ./cmd/server
    description: HTTP API server.
  admin:
    entrypoint: ./cmd/admin
    description: Administrative CLI.
  other-exec:
    entrypoint: ./other/main


# The `external` is used for third-party external tools/packages/libraries to define their configs. Each tool has to use a key and place their config under that key (e.g., external.myLinter) and should not place their config on the root of the file or directly inside the `external` object to create an isolation for all tools of the project. The `external` objects have no schema or specs and each tool is free to define their own config structure.
external:

  builderTool:
    path: ./main.go
    mode: strict

  myLinter:
    rules:
      - rule1
      - rule2
    ignore-dep: true

  awesomeReleaser:
    target: public

Go library of this repo

This repo, besides the spec of go.yaml, provides a light parser of go.yaml that other applications can use to avoid recreating a parser on their own everytime, even though you are free to use your own implementation.

The godotyaml library focuses on parsing go.yaml based on the schema version and maintains the data integrity and order of the file upon change.

A few points about this library:

• It is a library and not a CLI or executable
• It does not validate go.yaml. it only requires the file to be structurally valid YAML in order to parse. Malformed-but-parseable values are surfaced per-accessor (e.g. a non-integer schema_version returns an error from SchemaVersion()), while Load/Parse never reject a structurally valid file.
• It does not validate the semantic correctness of any value, such as URLs, licenses, etc.
• It does not enforce any schema on the sub-keys of external and it remains an open space for external tools to define their config
• It does not refuse to parse a go.yaml file if an unsupported field exists in the root of the file

Installation of library

go get github.com/vieolo/godotyaml

Usage of library

Read root metadata

doc, err := godotyaml.Load("go.yaml")
if err != nil {
    log.Fatal(err)
}

fmt.Println(doc.Name(), doc.Version())

execs, _ := doc.Executables()
fmt.Println(execs["server"].Entrypoint)

Read a tool's config

// Decode external.my-linter into your own type.
type lintConfig struct {
    Linters map[string][]string `yaml:"linters"`
}

var cfg lintConfig
ok, err := doc.DecodeExternalConfig("my-linter", &cfg)
if err != nil {
    log.Fatal(err)
}
if !ok {
    // section not present
}

// Or get the raw node and decode it yourself.
node, ok := doc.GetRawExternalConfig("my-linter")

Write a tool's config

// Updates only external.my-linter; every other section, all comments, and
// key ordering are left untouched.
err := doc.SetExternalConfig("my-linter", map[string]any{
    "linters": map[string]any{
        "enable": []string{"govet", "staticcheck"},
    },
})
if err != nil {
    log.Fatal(err)
}

if err := doc.Save("go.yaml"); err != nil {
    log.Fatal(err)
}

Documentation

Overview

Package godotyaml is the reference Go library for reading and writing go.yaml, a centralized config and metadata file for Go projects.

It is the parser/helper layer other tools depend on so they do not each roll their own YAML handling for go.yaml. A go.yaml file has two zones: a closed set of root project metadata (name, version, schema_version, executables, ...) exposed here as typed accessors, and an open external namespace where each tool stores arbitrary config under external.<toolname>. External sections are treated as opaque: the library reads them, hands them back to the caller to decode, and writes a single tool's section back without disturbing the rest of the file.

The yaml.v3 node tree is kept as the internal source of truth so that comments, key ordering, and unknown root keys survive a load/save cycle, and so that updating one tool's section never re-serializes (and never corrupts) the rest of the document.

Non-goals

godotyaml is deliberately small and unopinionated. It does NOT:

• validate the semantic correctness of any value (URLs, SPDX license identifiers, version strings, and so on are returned verbatim);
• enforce any schema on the external namespace;
• refuse to parse files with unknown root keys or unknown schema_version values — both are preserved and surfaced rather than rejected;
• expose helpers specific to any individual tool. No consuming tool is privileged; every tool's config lives at external.<toolname> on equal footing.

It is not a CLI, not a validator, and not a schema enforcer.

Index

• type Author
• type Document
  • func Load(path string) (*Document, error)
  • func Parse(r io.Reader) (*Document, error)
  • func (d *Document) Authors() ([]Author, error)
  • func (d *Document) DecodeExternalConfig(name string, out any) (bool, error)
  • func (d *Document) Description() string
  • func (d *Document) Documentation() string
  • func (d *Document) Executables() (Executables, error)
  • func (d *Document) ExternalConfigNames() []string
  • func (d *Document) GetRawExternalConfig(name string) (*yaml.Node, bool)
  • func (d *Document) Homepage() string
  • func (d *Document) IssueTracker() string
  • func (d *Document) License() string
  • func (d *Document) Name() string
  • func (d *Document) Repository() string
  • func (d *Document) Save(path string) error
  • func (d *Document) SchemaVersion() (int, error)
  • func (d *Document) SetExternalConfig(name string, value any) error
  • func (d *Document) Version() string
  • func (d *Document) Write(w io.Writer) error
• type Executable
• type Executables

Types

type Author

type Author struct {
	Name         string `yaml:"name"`
	Email        string `yaml:"email,omitempty"`
	Organization string `yaml:"organization,omitempty"`
	URL          string `yaml:"url,omitempty"`
}

Author describes a single entry in the root authors field. Only Name is expected to be present and the remaining fields are optional and tools may carry additional information the spec adds later by decoding the raw node directly.

type Document

type Document struct {
	Doc  *yaml.Node // the document node returned by the decoder
	Root *yaml.Node // the root mapping node (doc.Content[0])
}

Document is a parsed go.yaml file.

The underlying yaml.v3 node tree is the source of truth: typed accessors read from it on demand, and mutations edit it in place. Keeping the node tree canonical (rather than unmarshaling into a struct) is what lets the library preserve comments, key ordering, and unknown keys across a load/save cycle.

func Load

func Load(path string) (*Document, error)

reads and parses the go.yaml file at given path

func Parse

func Parse(r io.Reader) (*Document, error)

reads a go.yaml document from the given io.Reader

An empty input yields an empty document with a writable root mapping rather than an error, so callers can build a file from scratch.

func (*Document) Authors

func (d *Document) Authors() ([]Author, error)

Authors returns the root authors field as a list.

The field may appear in the file as a bare string, a single mapping, or a sequence of strings and/or mappings; all forms are normalized to []Author. A bare string becomes an Author with only Name set. It returns nil when the field is absent and an error only if a mapping entry cannot be decoded.

func (*Document) DecodeExternalConfig

func (d *Document) DecodeExternalConfig(name string, out any) (bool, error)

decodes external.<name> into out, reporting whether the section exists. It is a thin convenience over GetRawExternalConfig followed by node.Decode.

func (*Document) Description

func (d *Document) Description() string

Description returns the root description field, or "" if absent.

func (*Document) Documentation

func (d *Document) Documentation() string

Documentation returns the root documentation field (the project's docs URL), or "" if absent.

func (*Document) Executables

func (d *Document) Executables() (Executables, error)

Executables returns the root executables field, or nil if absent. Absence and an empty map are equivalent. It returns an error only if the section does not match the Executables shape.

func (*Document) ExternalConfigNames

func (d *Document) ExternalConfigNames() []string

returns the config names present under external, in document order.

func (*Document) GetRawExternalConfig

func (d *Document) GetRawExternalConfig(name string) (*yaml.Node, bool)

returns the raw yaml.Node for external.<name>, reporting whether the section exists.

The node is returned so the caller can decode it into its own types (node.Decode(&out)) without godotyaml imposing a structure on it. The node is the live tree node; treat it as read-only and use SetExternalConfig to write changes.

func (*Document) Homepage

func (d *Document) Homepage() string

Homepage returns the root homepage field (the project's website), or "" if absent.

func (*Document) IssueTracker

func (d *Document) IssueTracker() string

IssueTracker returns the root issue_tracker field, or "" if absent.

func (*Document) License

func (d *Document) License() string

License returns the root license field, or "" if absent.

func (*Document) Name

func (d *Document) Name() string

Name returns the root name field.

func (*Document) Repository

func (d *Document) Repository() string

Repository returns the root repository field, or "" if absent.

func (*Document) Save

func (d *Document) Save(path string) error

writes the document back to the file at path.

The file is rendered fully in memory first so a serialization error cannot leave a truncated file on disk.

func (*Document) SchemaVersion

func (d *Document) SchemaVersion() (int, error)

SchemaVersion returns the root schema_version as an integer.

The schema version is a single incrementing integer (0, 1, 2, ...). There are no minor versions such as 1.1. It returns (0, nil) when the key is absent. If the value is present but not a valid integer it returns a non-nil error: the file still parses (Load/Parse never reject it) and the malformed value is surfaced here rather than silently coerced. Quoted scalars (e.g. "1") are accepted.

func (*Document) SetExternalConfig

func (d *Document) SetExternalConfig(name string, value any) error

writes external.<name>, creating the external section if needed.

value may be any value yaml.v3 can marshal, or an existing *yaml.Node for callers that manage their own subtree (e.g. to preserve their own comments).

This function only touches the target section of `external` and sibling objects and the remainder of the file remains intact and untouched

func (*Document) Version

func (d *Document) Version() string

Version returns the root version field.

func (*Document) Write

func (d *Document) Write(w io.Writer) error

serializes the document to the given io.Writer, preserving comments and key ordering

Indentation is normalized to two spaces; yaml.v3 does not record the source file's original indent width, so that one stylistic detail is not preserved. Structure and ordering are

type Executable

type Executable struct {
	Entrypoint  string `yaml:"entrypoint"`            // directory holding package main, relative to project root
	Description string `yaml:"description,omitempty"` // optional human-readable purpose
}

Executable describes one executable entry point the project produces. It is project metadata only as it carries no output paths, OS/arch targets, build flags, or per-executable versions (every executable inherits the single project version). Build-specific concerns belong in a build tool's external.<toolname> section, not here.

type Executables

type Executables map[string]Executable

Executables maps an author-chosen executable name to its definition. Absence of the root key and an empty map are equivalent (both have length 0): the project produces no executables, i.e. it is a library.