85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
# 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`. |