The Context System provides an abstraction layer that enables the same GOBL invoice to be converted into different CII (Cross Industry Invoice) profile variants. Each context encapsulates five key configuration elements: the regulatory framework identifier, business process identifier, CII schema version, required GOBL addons, and validation specification ID.
For information about the actual conversion process that uses these contexts, see ConvertInvoice Function. For details about each supported standard, see Supported Formats Overview.
Diagram: Context struct definition with all five fields
The Context struct defines five fields that characterize each CII profile:
| Field | Type | Purpose | Required | Example |
|---|---|---|---|---|
GuidelineID | string | Identifies the regulatory framework and profile specification | Yes | "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0" |
BusinessID | string | Specifies the business process identifier (used by Peppol and XRechnung) | No | "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0" |
Version | string | CII schema version constant | Yes | VersionD16B or VersionD22B |
Addons | []cbc.Key | Required GOBL addons that must be present in the invoice | Yes | []cbc.Key{xrechnung.V3} |
VESID | string | Validation Exchange Specification ID for Phive validation | No | "de.xrechnung:cii:3.0.2" |
Sources: cii.go54-61 cii.go47-50
The package provides eight pre-configured contexts for common e-invoicing standards:
Diagram: Context hierarchy and relationships
Variable: ContextEN16931V2017 (default context)
| Field | Value |
|---|---|
| GuidelineID | "urn:cen.eu:en16931:2017" |
| BusinessID | "" (empty) |
| Version | VersionD16B |
| Addons | []cbc.Key{en16931.V2017} |
| VESID | "eu.cen.en16931:cii:1.3.13" |
Used for generic EN 16931 standard invoices providing maximum interoperability across EU member states. This is the default context used when no context is explicitly specified via WithContext.
Sources: cii.go64-69 cii.go181-183
Variable: ContextPeppolV3
| Field | Value |
|---|---|
| GuidelineID | "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0" |
| BusinessID | ProfileIDPeppolBilling ("urn:fdc:peppol.eu:2017:poacc:billing:01:1.0") |
| Version | VersionD16B |
| Addons | []cbc.Key{en16931.V2017} |
| VESID | "eu.cen.en16931:cii:1.3.13" |
Used for Peppol BIS Billing 3.0 invoices on the Peppol network.
Variable: ContextPeppolFranceFacturXV1
| Field | Value |
|---|---|
| GuidelineID | "urn:cen.eu:en16931:2017#conformant#urn:peppol:france:billing:Factur-X:1.0" |
| BusinessID | ProfileIDPeppolFranceBilling ("urn:peppol:france:billing:regulated") |
| Version | VersionD16B |
| Addons | []cbc.Key{ctc.Flow2V1} |
| VESID | "fr.factur-x:en16931:1.0.7-2" |
Used for Peppol France invoices with Factur-X profile.
Variable: ContextPeppolFranceCIUSV1
| Field | Value |
|---|---|
| GuidelineID | "urn:cen.eu:en16931:2017#compliant#urn:peppol:france:billing:cius:1.0" |
| BusinessID | ProfileIDPeppolFranceBilling ("urn:peppol:france:billing:regulated") |
| Version | VersionD22B |
| Addons | []cbc.Key{ctc.Flow2V1} |
| VESID | "eu.cen.en16931:cii:1.3.13" |
Used for Peppol France CIUS (Core Invoice Usage Specification) invoices. Note this uses VersionD22B.
Sources: cii.go72-78 cii.go89-95 cii.go98-104 cii.go41-44
Variable: ContextFacturXV1
| Field | Value |
|---|---|
| GuidelineID | "urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended" |
| BusinessID | "" (empty) |
| Version | VersionD16B |
| Addons | []cbc.Key{facturx.V1} |
| VESID | "fr.factur-x:extended:1.0.7-2" |
Franco-German hybrid PDF/XML invoice format (extended profile).
Variable: ContextZUGFeRDV2
| Field | Value |
|---|---|
| GuidelineID | "urn:cen.eu:en16931:2017#conformant#urn:zugferd.de:2p0:extended" |
| BusinessID | "" (empty) |
| Version | VersionD16B |
| Addons | []cbc.Key{zugferd.V2} |
| VESID | "de.zugferd:extended:2.3.2" |
German standard for PDF/A-3 embedded invoices (extended profile).
Variable: ContextChorusProV1
| Field | Value |
|---|---|
| GuidelineID | "A1" (default framework type) |
| BusinessID | "" (empty) |
| Version | VersionD16B |
| Addons | []cbc.Key{choruspro.V1} |
| VESID | "" (empty - no Phive validation) |
French public procurement platform. GuidelineID can be "A1" or "A2" depending on framework type.
Sources: cii.go81-86 cii.go107-112 cii.go124-129
Variable: ContextXRechnungV3
| Field | Value |
|---|---|
| GuidelineID | "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0" |
| BusinessID | ProfileIDPeppolBilling ("urn:fdc:peppol.eu:2017:poacc:billing:01:1.0") |
| Version | VersionD16B |
| Addons | []cbc.Key{xrechnung.V3} |
| VESID | "de.xrechnung:cii:3.0.2" |
German public sector standard, mandatory for B2G invoicing. Uses Peppol business process ID for routing.
Sources: cii.go115-121 cii.go41-44
Contexts are applied via the WithContext option function when calling Convert or ConvertInvoice:
Diagram: Context option flow through conversion functions
Sources: cii.go180-206 cii.go208-220
The gobl.cii convert command accepts a --context flag:
Diagram: CLI context string mapping to Context variables
Sources: cmd/gobl.cii/convert.go29 cmd/gobl.cii/convert.go40-56 cmd/gobl.cii/convert.go87
The WithContext function follows the functional options pattern defined in cii.go208-220:
| Type | Definition |
|---|---|
options struct | type options struct { context Context } |
Option function type | type Option func(*options) |
WithContext function | Returns an Option that sets o.context = context |
The Convert function builds the options struct and defaults to ContextEN16931V2017 if no context is provided:
Sources: cii.go208-220 cii.go181-186
When converting a GOBL invoice, the system validates that all required addons are present in the invoice:
Diagram: Addon validation flow in Convert function
This validation ensures that invoices are properly tagged with the required addons before conversion. The mapping is:
| Context | Required Addon |
|---|---|
ContextEN16931V2017 | en16931.V2017 |
ContextPeppolV3 | en16931.V2017 |
ContextFacturXV1 | facturx.V1 |
ContextZUGFeRDV2 | zugferd.V2 |
ContextXRechnungV3 | xrechnung.V3 |
ContextChorusProV1 | choruspro.V1 |
ContextPeppolFranceFacturXV1 | ctc.Flow2V1 |
ContextPeppolFranceCIUSV1 | ctc.Flow2V1 |
Sources: cii.go191-195
The VESID field in each context is used for external validation via the Phive gRPC service during testing. When the --validate flag is set, test cases validate the generated XML against the context's VESID:
Contexts without a VESID (like ContextChorusProV1) skip Phive validation.
Sources: examples_test.go103-112 cii.go59-60
The selected context directly affects the CII XML output in three key ways:
Diagram: Context fields mapping to CII XML elements
The context's GuidelineID and BusinessID are written to the ExchangedContext section:
Example with EN16931 context:
Example with XRechnung context:
The context's Version field determines the schemeVersionID attribute on various document elements. The two version constants are defined in cii.go44-48:
| Constant | Value | Usage |
|---|---|---|
VersionD16B | "D16B" | Used by most contexts (CII schema version D16B) |
VersionD22B | "D22B" | Used by ContextPeppolFranceCIUSV1 (CII schema version D22B) |
The context's Addons field controls which GOBL addons must be present in the source invoice for conversion to succeed. This validation happens at cii.go170-174 before any XML generation.
Sources: cii.go47-50 cii.go54-61 cii.go191-195
The test suite demonstrates context usage across different formats:
Each test validates that the context produces the correct GuidelineID and BusinessID in the output:
Sources: examples_test.go54-72 cii_test.go12-57
Refresh this wiki