GOBL Docs improvements

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.
 

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  <Tooltip tip="Unicode Character Set">UCS</Tooltip> 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
-      * &#x20;U+0009 Character Tabulation (tab)
-      * &#x20;U+000A Line Feed (newline)
-      * `\f` U+000C Form Feed
-      * &#x20;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.
 

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.

overview/inside.mdx

@@ -5,4 +5,4 @@ description: What does the GOBL logo on a document mean?
 
 <img src="/static/gobl_black.svg" height="30px" width="30px" alt="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.

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:[email protected]) 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:[email protected]) or [block a time in our calendar](https://www.invopop.com/contact).

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!

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.

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).

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