GOBL (Go Business Language)

The dsig package provides functionality for handling GoBL document digests and signatures. It uses the JOSE (Javascript Object Signing and Encryption) standards, specifically JWS (JSON Web Signatures - RFC7515) and JWK (JSON Web Keys - RFC7517).

GoBL uses the go-jose library under the hood but provides wrappers with sensible defaults optimized for GoBL document use cases. This ensures that signatures can be mathematically verified using a public key to confirm the identity of the private key owner.

GOBL Net is a decentralized discovery and delivery protocol for signed GOBL documents. It uses Fully Qualified Domain Names (FQDNs) to identify participants and relies on HTTPS to bind addresses to three well-known resources:

• /.well-known/gobl/keys/<kid>: Publishes a single verification key (RFC 7517 JWK).
• /.well-known/gobl/who: Publishes a signed org.Party identity.
• /.well-known/gobl/inbox: Accepts signed GOBL envelopes.

Verification is achieved by obtaining the issuer's key from their domain and relying on Web PKI to authenticate the HTTPS response. Registration authorities can add a trust layer by countersigning party envelopes.

Use rules.When to apply a subset of rules only when a specific condition is met. Conditions are evaluated based on the object's state, as rules do not have access to context.Context.

To ensure faults land on the correct field when a requirement is conditional, combine is.Not with rules.When.

// Apply rules for 'stamps' only if the envelope is not signed
rules.When(is.Func("not signed", envelopeNotSigned),
    rules.Field("stamps",
        rules.Assert("12", "stamps not allowed before signing", is.Length(0, 0)),
    ),
)

Addons are used to add normalization, validation rules, and specific scenarios to a GOBL document to adapt it to a particular format or regulatory regime.

To use an addon, a document must list the addon's versioned key (e.g., mx-cfdi-v4) under the $addons field in its JSON representation.

There are two types of addons:

1. In-core addons: These are part of the main github.com/invopop/gobl package and are automatically available when you import the core library.
2. External addons: These live in their own Go modules (e.g., github.com/invopop/gobl.fr.ctc). These allow for country-specific rules to be opted into only when needed, keeping the core library lightweight.

In GOBL, an Envelope is a wrapper used to hold business document data (like an Invoice). The envelope provides functionality to guarantee that the underlying payload has not been modified. Instead of working directly on the document, you insert your document into an envelope to manage its lifecycle and integrity.

// Prepare an "Envelope"
env := gobl.NewEnvelope()
if err := env.Insert(inv); err != nil {
	panic(err)
}

A standard delivery in GOBL Net follows these steps:

1. Discovery: The sender obtains the receiver's address out of band.
2. Inquiry (Optional): The sender may call /who to retrieve the receiver's invoicing details.
3. Signing: The sender signs the envelope with iss=sender and aud=receiver.
4. Submission: The sender posts the envelope to the receiver's inbox using a request token.
5. Verification: The receiver verifies the token and calls VerifyDelivery.
6. Endorsement (Optional): The receiver may call VerifySender on the returned issuer.
7. Confirmation: A 202 status code confirms durable receipt.

Note: Only step 6 requires authority endorsement, and that requirement applies to the sender. Any response document is treated as a new delivery and is subject to the same rules.

Addons adapt GOBL documents to specific formats or regulatory regimes. They add extensions, normalization, and validation rules identified by a versioned key under the $addons field in the JSON (e.g., es-facturae-v3).

While many addons are bundled in the core library, some must be imported separately as Go modules:

• gobl.br.nfe (Brazil NF-e, br-nfe-v4)
• gobl.br.nfse (Brazil NFS-e, br-nfse-v1)
• gobl.fr.ctc (France CTC flows)
• gobl.mx.cfdi (Mexican SAT CFDI, mx-cfdi-v4)
• gobl.pt.saft (Portugal SAF-T, pt-saft-v1)
• gobl.sa.zatca (Saudi Arabia ZATCA, sa-zatca-v1)

For a complete set of addons including these external ones, use the gobl.dev project.

When defining validation rules in GOBL, follow this order of preference to ensure maintainability and reuse:

1. rules/is: Use generic tests for standard types (strings, ints, slices, etc.).
2. Domain packages: Check if the package defining your type (e.g., num, tax, org) already exports a test for it.
3. Custom function: Only use is.Func or is.StringFunc if neither of the above expresses the required rule.

Best Practice: If you write a custom rule that is generally useful for a GOBL type, add that test to the type's own package rather than keeping it private to your specific addon or implementation.