This section covers everything needed to contribute to the gobl.cii library: repository layout, how the test suite works, how generated XML is validated against external schemas, code quality tooling, and the CI/CD pipeline. Each sub-page focuses on a single concern.
For information on what the library does and how to use it as a consumer, see the Getting Started section. For API reference details, see the Core Conversion API section.
| Sub-page | Topic |
|---|---|
| Project Structure | Directory layout, file responsibilities, package boundaries |
| Testing Framework | Golden-file tests, --update flag, Saxon XSLT tooling |
| Validation Tools | Phive schema validation, --validate flag, VESID field |
| Code Quality Standards | golangci-lint configuration, enabled linters |
| CI/CD Pipeline | GitHub Actions workflows: Lint, Test, Release |
| Contributing Guidelines | Forking, branching, commit conventions, PR process |
Development workflow diagram: contributor actions and tooling
Sources: README.md, examples_test.go
The following table maps the main development concerns to the concrete code and configuration files involved.
| Concern | Primary File(s) | Key Symbols |
|---|---|---|
| Public API surface | cii.go | Convert, Parse, Unmarshal, WithContext, Context |
| CLI entry point | cmd/gobl.cii/convert.go | convertOpts, runE |
| Example / golden tests | examples_test.go | TestConvertToInvoice, TestParseInvoice, newInvoiceFrom, loadEnvelope |
| Test fixtures | test/data/convert/, test/data/parse/ | per-context subdirectories with .json / .xml files |
| Phive validation | examples_test.go | validate flag, phive.ValidationServiceClient, ctx.context.VESID |
| Linting | .golangci.yaml | configured linter set |
| CI workflows | .github/workflows/ | Lint, Test Go, Release |
Sources: cii.go, cmd/gobl.cii/convert.go, examples_test.go
Golden-file tests read from and write to a structured directory under test/data/. Understanding this layout is essential before editing conversion logic.
Diagram: test data directory structure and test function mapping
Sources: examples_test.go
# Run all tests (compare output against golden files)
go test ./...
# Regenerate golden files after changing conversion logic
go test ./... -update
# Validate generated XML against Phive schema service
# (requires a running Phive instance on localhost:9091)
go test ./... -validate
The -update flag is controlled by the updateOut variable and the -validate flag by the validate variable, both defined in examples_test.go. When -validate is set, each context whose VESID field is non-empty is submitted to the Phive gRPC endpoint at localhost:9091.
Sources: README.md, examples_test.go
Each context constant defined in cii.go has a corresponding subdirectory under test/data/convert/ and test/data/parse/. When adding a new context or modifying an existing one, both directories may need to be updated.
| Context Constant | Test Directory | VESID (for Phive) |
|---|---|---|
ContextEN16931V2017 | en16931/ | eu.cen.en16931:cii:1.3.13 |
ContextPeppolV3 | peppol/ | eu.cen.en16931:cii:1.3.13 |
ContextFacturXV1 | facturx/ | fr.factur-x:extended:1.0.7-2 |
ContextXRechnungV3 | xrechnung/ | de.xrechnung:cii:3.0.2 |
ContextZUGFeRDV2 | zugferd/ | de.zugferd:extended:2.3.2 |
ContextChorusProV1 | choruspro/ | (none — skipped) |
ContextPeppolFranceFacturXV1 | peppol-france-facturx/ | fr.factur-x:en16931:1.0.7-2 |
ContextPeppolFranceCIUSV1 | peppol-france-cius/ | eu.cen.en16931:cii:1.3.13 |
Sources: cii.go, examples_test.go
cii package (cii.go).GOBL → CII and CII → GOBL directions; see Project Structure for package boundaries.-update.For the full details of each concern, navigate to the relevant sub-page listed in the table at the top of this page.