go-ocds/README.md

go-ocds (ocdsgen)

OCDS 1.1 types for Go, with extensions chosen per package.

The module contains a generator and some ready-made profiles:

cmd/ocdsgen/          CLI entry point (Cobra)
internal/cli/         command definitions: generate, resolve, schema
internal/generator/   fetch, resolve, merge and emit (no CLI code)
profiles/core/        no extensions
profiles/eu/          EU profile
profiles/uk/          UK extension to the EU profile
profiles/findTender/  UK gov Find A Tender service profile with extensions
example/              a consumer module generating its own packages

Every generated package is self-contained: it imports only the standard library, so a package's types depend only on its own extensions.json.

Use a ready-made profile

go get git.avsdev.uk/Go/go-ocds@v1.0.0

import "git.avsdev.uk/Go/go-ocds/profiles/uk"
var r uk.Release

Generate your own packages

Give each package its own extensions.json and a directive:

//go:generate go tool ocdsgen generate -c extensions.json -o ocds_gen.go -p tenders

Pin the generator in your go.mod (Go 1.24+):

go get -tool git.avsdev.uk/Go/go-ocds/cmd/ocdsgen@v1.0.0

On older Go, add a tools.go with a blank import of git.avsdev.uk/Go/go-ocds/cmd/ocdsgen behind //go:build tools, and use go run git.avsdev.uk/Go/go-ocds/cmd/ocdsgen in the directive (see example/).

Then go generate ./... and commit the generated ocds_gen.go files.

Commands

ocdsgen generate [-c extensions.json] [-o ocds_gen.go] [-p name] [--check]
ocdsgen resolve  [-c extensions.json] [--json]
ocdsgen schema   [-c extensions.json] [--kind release|package] [-o file]

Global flags: --strict fails on any warning, -q/--quiet hides notes and warnings, --timeout sets the per-request HTTP timeout. Run ocdsgen <command> --help for details.

• generate writes the Go types. -p defaults to the output directory's name. -o - writes to stdout. --check writes nothing and fails if the file is missing or stale, for CI: ocdsgen generate --check --strict.
• resolve lists every extension the config pulls in, dependencies first, in the order their patches are applied.
• schema writes the merged JSON Schema the types are generated from, for debugging a config or validating data with other tools.

Paths in a config that aren't URLs are resolved relative to the config file, so a project can keep private or vendored extensions alongside it.

Adding a profile to this module

Create profiles/<name>/ with extensions.json and a generate.go like the existing ones, run go generate ./..., and tag a release.

Generator warnings

• two extensions give the same field different types (the later one wins);
• the same extension repo is included at two versions;
• a definition is never referenced, which usually means an extension patches a type (e.g. Lot) whose defining extension (e.g. Lots) isn't in the config.

Type mapping

• date-time → *time.Time,
• integer → *int,
• number → *float64,
• boolean → *bool,
• ["string","integer"] → ID,
• objects without properties → map[string]any,
• anything ambiguous → json.RawMessage.
• All non-required fields are omitempty.