diff --git a/addons/overview.mdx b/addons/overview.mdx index f1aecd0..cbdac38 100644 --- a/addons/overview.mdx +++ b/addons/overview.mdx @@ -6,7 +6,7 @@ Addons in GOBL have a similar objective to namespaces in XML documents, but with When an addon is applied to a GOBL document that supports them, the calculation and validation steps will automatically use all the addon's specifications to ensure that all the data complies with whatever is required by the standard or format represented. -A great example of this is the `mx-cfdi-v4` addon. When applied to an invoice, it will automatically ensure that any extensions and validation rules are performed, so that document can subsequently be processed by a conversion tool into the local XML CFDI format, in the case, [gobl.cfdi](https://github.com/invopop/gobl.cfdi). +A great example of this is the `mx-cfdi-v4` addon. When applied to an invoice, it will automatically ensure that any extensions and validation rules are performed, so that document can subsequently be processed by a conversion tool into the local XML CFDI format, in this case, [gobl.cfdi](https://github.com/invopop/gobl.cfdi). The key advantage with addons is that the original content of the GOBL invoice is still intact, maintaining the global compatibility, but ensuring that any local or format restrictions are accounted for. diff --git a/overview/canonicalization.mdx b/overview/canonicalization.mdx index 3937b69..2428f93 100644 --- a/overview/canonicalization.mdx +++ b/overview/canonicalization.mdx @@ -27,32 +27,36 @@ GOBL considers the following JSON values as explicit types: JSON in canonical form: -1. MUST be encoded in VALID [UTF-8](https://tools.ietf.org/html/rfc3629). A document with invalid character encoding will be rejected. -2. MUST NOT include insignificant whitespace. -3. MUST order the attributes of objects lexicographically by the UCS (Unicode Character Set) code points of their names. -4. MUST remove attributes from objects whose value is `null`. -5. MUST NOT remove null values from arrays. -6. MUST represent integer numbers, those with a zero-valued fractional part, WITHOUT: - 1. a leading minus sign when the value is zero, - 2. a decimal point, - 3. an exponent, thus limiting numbers to 64 bits, and - 4. insignificant leading zeroes, as already required by JSON. -7. MUST represent floating point numbers in exponential notation, INCLUDING: - 1. a nonzero single-digit part to the left of the decimal point, - 2. a nonempty fractional part to the right of the decimal point, - 3. no trailing zeroes to right of the decimal point except to comply with the previous point, - 4. a capital `E` for the exponent indicator, - 5. no plus sign in the [mantissa](https://en.wikipedia.org/wiki/Significand) nor exponent, and - 6. no insignificant leading zeros in the exponent. -8. MUST represent all strings, including object attribute keys, in their minimal length UTF-8 encoding: +1. **Must** be encoded in [valid UTF-8](https://tools.ietf.org/html/rfc3629). A document with invalid character encoding will be rejected. +2. **Must not** include superfluous or non-semantic whitespace. +3. **Must** order the attributes of objects lexicographically by the UCS code points of their names. +4. **Must** remove attributes from objects whose value is `null`. +5. **Must not** remove null values from arrays. +6. **Must** represent numbers that are mathematically integers—i.e., those with a zero-valued fractional part—using the canonical JSON integer form. These numbers **must not** be represented with: + * a leading minus sign when the value is zero (i.e., use `0`, not `-0`); + * a decimal point (e.g., `3`, not `3.0`); + * exponent notation (e.g., `1000`, not `1e3`); + * leading zeroes (e.g., `42`, not `042`), as already prohibited by the JSON specification. +7. **Must** represent floating-point numbers in **exponential notation**, adhering to the following format: + * A **nonzero single-digit** integer part to the left of the decimal point (e.g., `1.23E+3`, not `12.3E+2`); + * A **nonempty fractional part** to the right of the decimal point (e.g., `1.2E3`, not `1.E3`); + * **No trailing zeroes** in the fractional part, unless required to satisfy the condition above; + * A capital **`E`** as the exponent separator (not lowercase `e`); + * **No plus sign** (`+`) in either the mantissa or the exponent; + * **No leading zeroes** in the exponent (e.g., `1.2E3`, not `1.2E003`). +8. **Must** represent all strings, including object attribute keys, in their minimal length UTF-8 encoding: 1. using two-character escape sequences where possible for characters that require escaping, specifically: - * `\"` U+0022 Quotation Mark - * `\\` U+005C Reverse Solidus (backslash) - * `\b` U+0008 Backspace - * U+0009 Character Tabulation (tab) - * U+000A Line Feed (newline) - * `\f` U+000C Form Feed - * U+000D Carriage Return + + | Character | Escape Sequence | Unicode | + | --------------------------- | --------------- | ------- | + | `"` Quotation Mark | `\"` | `U+0022` | + | `\` Reverse Solidus (backslash) | `\\` | `U+005C` | + | `⌫` Backspace | `\b` | `U+0008` | + | `⇥` Character Tabulation (tab) | `\t` | `U+0009` | + | `␊` Line Feed (newline) | `\n` | `U+000A` | + | `␌` Form Feed | `\f` | `U+000C` | + | `↵` Carriage Return | `\r` | `U+000D` | + 2. using six-character `\u00XX` uppercase hexadecimal escape sequences for control characters that require escaping but lack a two-character sequence described previously, and 3. reject any string containing invalid encoding. diff --git a/overview/components.mdx b/overview/components.mdx index d0752f0..4ea18fd 100644 --- a/overview/components.mdx +++ b/overview/components.mdx @@ -22,4 +22,4 @@ The aim is to build a single resource that developers can use to determine what We have be realistic, the US tax system for example is a total mess and incredibly difficult to put into code, but for most countries around the world based on a VAT or GST system there is hope for trying to put the tax types, rates, and rules into a structured format. -Each tax regime in GOBL is defined in Go as structured data and automatically converted into [JSON files](https://github.com/invopop/gobl/tree/main/data/regimes) that conform to the [tax.Regime](/draft-0/tax/regime) schema specification. Every regime is identified by a code based on the country they represent. +Each tax regime in GOBL is defined in Go as structured data and automatically converted into [JSON files](https://github.com/invopop/gobl/tree/main/data/regimes) that conform to the [tax.Regime](/regimes/overview) schema specification. Every regime is identified by a code based on the country they represent. diff --git a/overview/inside.mdx b/overview/inside.mdx index 44e19e4..b8cb80d 100644 --- a/overview/inside.mdx +++ b/overview/inside.mdx @@ -5,4 +5,4 @@ description: What does the GOBL logo on a document mean? GOBL Icon -If you see the GOBO logo on a PDF document, it means that a GOBL JSON envelope has been embedded as an attachment. Rather than trying to copy and paste the details, use a tool that can extract the attachment and parse it using GOBL. +If you see the GOBL logo on a PDF document, it means that a GOBL JSON envelope has been embedded as an attachment. Rather than trying to copy and paste the details, use a tool that can extract the attachment and parse it using GOBL. diff --git a/overview/support.mdx b/overview/support.mdx index b8cd059..96d4cc9 100644 --- a/overview/support.mdx +++ b/overview/support.mdx @@ -8,8 +8,8 @@ The complexity around invoicing and in particular electronic invoicing can quick - [Issues](https://github.com/invopop/gobl/issues) for specific problems with GOBL related to code or usage. Each of the projects in the [tools section](/overview/tools) will also have their own issues pages. - [Discussions](https://github.com/invopop/gobl/discussions) for open discussions about the future of GOBL, complications with a specific country, proposals, or any open ended issues. -- [Slack](https://join.slack.com/t/goblschema/shared_invite/zt-20qu1s0cm-AUE8oYbGly681EsYdDiqxw) for real-time chat about something specific or urgent. We always encourage you to use one of the others options which are indexed and searchable, but if you'd like to bring something to attentional quickly, this is a great resource. +- [Slack](https://join.slack.com/t/goblschema/shared_invite/zt-20qu1s0cm-AUE8oYbGly681EsYdDiqxw) when something is urgent or highly specific. We encourage you to use the other options as they’re indexed and searchable. Slack is ideal for quickly bringing something to the team's attention. ## Commercial -[Invopop](https://invopop.com) is the company behind GOBL and offers a fully hosted workflow engine to automate you electronic invoicing needs. Drop us an [email](email:support@invopop.com) or [block a time in our calendar](https://www.invopop.com/contact). +[Invopop](https://www.invopop.com) is the company behind GOBL and offers a fully hosted workflow engine to automate you electronic invoicing needs. Drop us an [email](email:support@invopop.com) or [block a time in our calendar](https://www.invopop.com/contact). diff --git a/overview/tools.mdx b/overview/tools.mdx index d4bcf4f..96e9856 100644 --- a/overview/tools.mdx +++ b/overview/tools.mdx @@ -16,7 +16,7 @@ The main libraries and tools for GOBL processing: Aside from the main GOBL repository which can be used directly inside your Go projects, the following tools are designed to help construct GOBL files: -- [GOBL Builder](https://build.gobl.org) [source](https://github.com/invopop/gobl.builder) - learn and discover how to build GOBL documents from the comfort of your web browser. The editor leverages the GOBL CLI WASM binary so you can run validation and calculation processes directly. +- [GOBL Builder](https://build.gobl.org) · [Source](https://github.com/invopop/gobl.builder) - learn and discover how to build GOBL documents from the comfort of your web browser. The editor leverages the GOBL CLI WASM binary so you can run validation and calculation processes directly. - [GOBL for Ruby](https://github.com/invopop/gobl.ruby) - Easily build or read GOBL documents in Ruby. We'd love for GOBL to be available in more languages. If you'd like to contribute, checkout the [GOBL Generate](https://github.com/invopop/gobl.generator) mentioned above and open a discussion! diff --git a/overview/versions.mdx b/overview/versions.mdx index 8a8c062..e3b69cc 100644 --- a/overview/versions.mdx +++ b/overview/versions.mdx @@ -4,11 +4,11 @@ title: "Versions" GOBL follows [semver](https://semver.org) and [Go Module Versioning](https://go.dev/doc/modules/version-numbers) best practices for all code based projects. Versions require `v` to be in front of the semver, for example: `v0.18.0`. When deciding what type of release to make, we take in the following considerations for each level: -- Patch - typically a bug fix or change to documentation with no expected side effects. May incorporate changes to the internal structures that do not result in a modified Schema. -- Minor - significant changes that must not alter existing functionality. Adding support for a new region or support for a new type of structure are good examples. While we're still developing `v0`, changes may be more significant. -- Major - changes that will break previous implementations and should not be considered compatible. Once we hit the `v1` milestone, our objective is to try and avoid major releases as much as possible. +- **Patch** - typically a bug fix or change to documentation with no expected side effects. May incorporate changes to the internal structures that do not result in a modified Schema. +- **Minor** - significant changes that must not alter existing functionality. Adding support for a new region or support for a new type of structure are good examples. While we're still developing `v0`, changes may be more significant. +- **Major** - changes that will break previous implementations and should not be considered compatible. Once we hit the `v1` milestone, our objective is to try and avoid major releases as much as possible. -JSON Schemas created by GOBL use a simplified approach and only include the "major" version in sources. A few observations: +JSON Schemas created by GOBL use a simplified approach and only include the _major_ version in sources. A few observations: - Schema versions match GOBL major versions. - GOBL `v0` releases will use `draft-0` in schemas for more closer alignment to JSON Schema expectations. diff --git a/quick-start/cli.mdx b/quick-start/cli.mdx index 5d0885a..ab742e7 100644 --- a/quick-start/cli.mdx +++ b/quick-start/cli.mdx @@ -162,4 +162,4 @@ The output produced should be something like: Essentially the `doc` and `head` fields are identical to the original message, but we've now added the `sigs` array at the end. Combined with your public key, anyone can easily verify the contents of your message where indeed signed with your private key. -If you're interested, you can check the contents of the signature here: [jwt.io](https://jwt.io). +If you're interested, you can check the contents of the signature at [jwt.io](https://jwt.io). diff --git a/quick-start/invoices.mdx b/quick-start/invoices.mdx index f14fcb8..36a3df9 100644 --- a/quick-start/invoices.mdx +++ b/quick-start/invoices.mdx @@ -2,7 +2,7 @@ title: "Invoices" --- -For this guide, we assume you already have already successfully followed in the steps in the CLI Quick Start. +For this guide, we assume you already have already successfully followed in the steps in the [CLI Quick Start](/quick-start/cli). Creating an invoice is one of the most useful features of GOBL as it demonstrates the full power of the library. For the sake of the examples on this page, we're using Spain as the base region, but everything here should be supported with minor modifications in any other supported country. @@ -197,7 +197,7 @@ And open it either from the command line if supported by your system, or directl open output.pdf ``` -You'll notice that the resulting PDF has a big "DRAFT" message in the middle. If you want to remove this, you'll have to sign the document with: +The resulting PDF will have a large "DRAFT" watermark on all pages. To remove this, sign the document with: ```bash gobl sign -i invoice.yaml > invoice.json diff --git a/static/favicon.svg b/static/favicon.svg index 8f08e3a..8bf942f 100644 --- a/static/favicon.svg +++ b/static/favicon.svg @@ -1,4 +1 @@ - - - - + \ No newline at end of file diff --git a/static/gobl_black.svg b/static/gobl_black.svg index d3ec4b1..1e5bc07 100644 --- a/static/gobl_black.svg +++ b/static/gobl_black.svg @@ -1,29 +1 @@ - - - - - - - - - - - - - - - + \ No newline at end of file diff --git a/static/logo.svg b/static/logo.svg index 47c04ba..02bb562 100644 --- a/static/logo.svg +++ b/static/logo.svg @@ -1,14 +1 @@ - - - - - - - - - - - - - - \ No newline at end of file + \ No newline at end of file diff --git a/static/logo_long_dark.svg b/static/logo_long_dark.svg index 33179f5..99cd1ee 100644 --- a/static/logo_long_dark.svg +++ b/static/logo_long_dark.svg @@ -1,12 +1 @@ - - - - - - - - - - - - \ No newline at end of file + \ No newline at end of file diff --git a/static/logo_long_light.svg b/static/logo_long_light.svg index b73087f..b741566 100644 --- a/static/logo_long_light.svg +++ b/static/logo_long_light.svg @@ -1,12 +1 @@ - - - - - - - - - - - - \ No newline at end of file + \ No newline at end of file diff --git a/use-cases/invoicing.mdx b/use-cases/invoicing.mdx index 85b14ce..39a898f 100644 --- a/use-cases/invoicing.mdx +++ b/use-cases/invoicing.mdx @@ -36,14 +36,14 @@ In GOBL, an Invoice is represented by [bill.Invoice](/draft-0/bill/invoice). There are some basic universal sections you'll need to be aware about for any invoice: -- _Type_ - is this is standard invoice, proforma, credit note, etc. -- _Issue Date_ - an issue date shows when the invoice was sent, and there may also be "value" and "operation" dates. -- _Code_ - a single unique code that identifies the invoice, possibly also with an associated _series_ to help group documents together. Most countries require codes to be generated consecutively. -- _Supplier_ - the party responsible for issuing the invoice, supplying the services, and requesting payment. Essential data would include the name, address, contact details, and most importantly, a country specific Tax Identity. -- _Customer_ - similar to the supplier, this is the party responsible for receiving the invoice, goods or services, and subsequently paying. A _customer_ may not be required if issuing a simplified invoice. -- _Lines_ & _Item_ - descriptions of what exactly is being sold, including their price, discounts, and any taxes that need to be applied. -- _Payment_ - not strictly necessary, but often included, these are instructions that help customers know how they need to send payment, or perhaps indications of what was already paid. -- _Totals_ - summary of the line item totals and taxes. +- **Type** - is this is standard invoice, proforma, credit note, etc. +- **Issue Date** - an issue date shows when the invoice was sent, and there may also be "value" and "operation" dates. +- **Code** - a single unique code that identifies the invoice, possibly also with an associated _series_ to help group documents together. Most countries require codes to be generated consecutively. +- **Supplier** - the party responsible for issuing the invoice, supplying the services, and requesting payment. Essential data would include the name, address, contact details, and most importantly, a country specific Tax Identity. +- **Customer** - similar to the supplier, this is the party responsible for receiving the invoice, goods or services, and subsequently paying. A _customer_ may not be required if issuing a simplified invoice. +- **Lines & Item** - descriptions of what exactly is being sold, including their price, discounts, and any taxes that need to be applied. +- **Payment** - not strictly necessary, but often included, these are instructions that help customers know how they need to send payment, or perhaps indications of what was already paid. +- **Totals** - summary of the line item totals and taxes. Of course, there are many more fields that can be added to an invoice document, but these are the basics. @@ -70,8 +70,8 @@ GOBL defines a specific set of common [types](/draft-0/bill/invoice#type-values) - `standard` - a regular commercial invoice between a supplier and customer. - `proforma` - used to send a "preview" of the final invoice to a customer for their approval. If a customer approves a proforma invoice, they're effectively entering into a contract with the supplier for the services or goods to be supplied, so while tax agencies don't consider this an essential type for tax collection, they can have legal consequences. -- `corrective` - indicates that this invoice performs corrections to a previous invoice identified in the `preceding` property defined as a [bill.Preceding](/draft-0/bill/preceding). -- `credit-note` - traditional and most frequently used type when a supplier needs to issue a refund or cancel part of a [preceding](/draft-0/bill/preceding) invoice. +- `corrective` - indicates that this invoice performs corrections to a previous invoice identified in the `preceding` property which is defined as an array of [Org.DocumentRef](/draft-0/org/document_ref). +- `credit-note` - traditional and most frequently used type when a supplier needs to issue a refund or cancel part of a preceding invoice. - `debit-note` - indicates that the preceding invoice was incomplete and there are now some additional costs. Most companies will just issue a new invoice to complement the previous one as opposed to issuing a specific debit note. Not every country will have support for all these types. Spain for example doesn't have support for credit-notes, and instead requires corrective invoices, more details below.