Jgperrin finetune doc

CHANGELOG.md

@@ -8,9 +8,9 @@ This document tracks the history and evolution of the **Open Data Contract Stand
 
 # v3.1.0 - 2025-11-20 - PROPOSED
 
+* **Splits** Main specification document into several smaller documents. 
 * Most sections have gained an optional `id` to enable easier linking as per RFC 26.
 * The **`team`** block is accepting both ODCS v3.0.x structure (now obsolete) or the updated RFC16 structure. The obsolete structure will be removed in ODCS v4.
-* **Splits** Main specification document into several smaller documents. 
 * **Adds** Relationships (Foreign Keys):
   * Add `relationships` array field to both `SchemaObject` and `SchemaProperty` to define foreign key relationships.
   * Support for property-level relationships where `from` field is implicit.

docs/custom-other-properties.md

@@ -7,6 +7,8 @@ description: "This section covers custom properties you may find in a data contr
 
 This section covers other properties you may find in a data contract.
 
+[Back to TOC](README.md)
+
 ## Custom Properties
 
 This section covers custom properties you can use to add non-standard properties. This block is available in many
@@ -63,3 +65,4 @@ contractCreatedTs: 2024-09-17T11:58:08Z
 |-------------------|----------------------|----------|-------------------------------------------------------------------------|
 | contractCreatedTs | Contract Created UTC | No       | Timestamp in UTC of when the data contract was created, using ISO 8601. |
 
+[Back to TOC](README.md)

docs/data-quality.md

@@ -14,6 +14,8 @@ Data quality rules support different levels/stages of data quality attributes:
 * **SQL**: An individual SQL query that returns a value that can be compared.
 * **Custom**: Quality attributes that are vendor-specific, such as Soda, Great Expectations, dbt tests, dbx, or Montecarlo monitors.
 
+[Back to TOC](README.md)
+
 ## Text
 
 A human-readable text that describes the quality of the data. Later in the development process, these might be translated into an executable check (such as `sql`), a library metric, or checked through an AI engine.
@@ -329,3 +331,5 @@ quality:
     mustBeLessThan: 100
 ```
 
+[Back to TOC](README.md)
+

docs/fundamentals.md

@@ -7,6 +7,8 @@ description: "This section contains general information about the contract."
 
 This section contains general information about the contract.
 
+[Back to TOC](README.md)
+
 ## Example
 
 ```YAML
@@ -50,3 +52,5 @@ tags: ['finance']
 | description.usage                    | Usage                     | No       | Recommended usage of the data.                                                                                                                                                                                                |
 | description.authoritativeDefinitions | Authoritative Definitions | No       | List of links to sources that provide more details on the dataset; examples would be a link to privacy statement, terms and conditions, license agreements, data catalog, or another tool.                                    |
 | description.customProperties         | Custom Properties         | No       | Custom properties that are not part of the standard.                                                                                                                                                                          |
+
+[Back to TOC](README.md)

docs/infrastructure-servers.md

@@ -16,6 +16,8 @@ The typical ways of using the top level `servers` element are as follows:
 * **Different Technologies:** The data contract makes sure that regardless of the offered technology, it still holds. *Example:* a data product offers its data in a Kafka topic and in a BigQuery table that should have the same structure and content.
 * **Different Technologies and Multiple Environments:** The data contract makes sure that regardless of the offered technology and environment, it still holds. *Example:* a data product offers its data in a Kafka topic and in a BigQuery table that should have the same structure and content in dev(elopment), UAT, and prod(uction).
 
+[Back to TOC](README.md)
+
 ## General Server Structure
 
 Each server in the schema has the following structure:
@@ -359,3 +361,5 @@ Actian Zen (formerly Btrieve, later named Pervasive PSQL until version 13) is an
 | warehouse   | Warehouse         | No       | Name of the cluster or warehouse.                                   |
 
 If you need another property, use [custom properties](./custom-other-properties.md).
+
+[Back to TOC](README.md)

docs/pricing.md

@@ -7,6 +7,9 @@ description: "This section covers pricing when you bill your customer for using
 
 This section covers pricing when you bill your customer for using this data product.
 
+[Back to TOC](README.md)
+
+
 ## Example
 
 ```YAML
@@ -24,3 +27,5 @@ price:
 | price.priceAmount   | Price Amount       | No       | Subscription price per unit of measure in `priceUnit`.                 |
 | price.priceCurrency | Price Currency     | No       | Currency of the subscription price in `price.priceAmount`.             |
 | price.priceUnit     | Price Unit         | No       | The unit of measure for calculating cost. Examples megabyte, gigabyte. |
+
+[Back to TOC](README.md)

docs/references.md

@@ -10,6 +10,8 @@ This section describes how to reference elements within a data contract schema.
 > [!IMPORTANT]
 > References are currently only supported for foreign key relationships.
 
+[Back to TOC](README.md)
+
 ## Fully Qualified Reference Notation
 
 ODCS uses a fully qualified notation with the `id` field and slash-separated paths for stable, refactor-safe references.
@@ -380,3 +382,5 @@ schema:
             name: postal_code
             logicalType: string
 ```
+
+[Back to TOC](README.md)

docs/resources.md

@@ -28,6 +28,7 @@ If you spot an article about the Open Data Contract Standard, make a pull reques
 
 ## Books
 
+* 2025-10-05 - **Building Data Products**, [O'Reilly](https://www.oreilly.com/library/view/building-data-products/9798341629394/), currently in writing.
 * 2024-09-01 - **Implementing Data Mesh**, [O'Reilly](https://www.oreilly.com/library/view/implementing-data-mesh/9781098156213/), [Amazon](https://amzn.to/3ysN3Jf): in Chapter 5, ODCS is extensively used & described.
 * 2024-01-20 - **Data Contracts for all ages**, [Amazon](https://amzn.to/3Wl1My1).
 
@@ -37,6 +38,5 @@ If you spot a book about the Open Data Contract Standard, make a pull request!
 
 * 2025-03-28 - [What is a Data Contract? - DataFriday 5x01](https://www.youtube.com/watch?v=Iq6SxdsIHHE)
 * 2024-01-02 - [What is a Data Contract? from IBM Technology](https://www.youtube.com/watch?v=-n3OD-ml_k0)
-*
 
 If you spot a video about the Open Data Contract Standard, make a pull request!

docs/roles.md

@@ -1,11 +1,13 @@
 ---
 title: "Roles"
-description: "This section lists the roles that a consumer may need to access the dataset depending on the type of access they require."
+description: "This section lists the roles that a consumer may need to access the dataset, depending on the type of access they require."
 ---
 
 # Roles
 
-This section lists the roles that a consumer may need to access the dataset depending on the type of access they require.
+This section lists the roles that a consumer may need to access the dataset, depending on the type of access they require.
+
+[Back to TOC](README.md)
 
 ## Example
 
@@ -40,3 +42,5 @@ roles:
 | roles.firstLevelApprovers  | 1st Level Approvers | No       | The name(s) of the first-level approver(s) of the role.              |
 | roles.secondLevelApprovers | 2nd Level Approvers | No       | The name(s) of the second-level approver(s) of the role.             |
 | roles.customProperties     | Custom Properties   | No       | Any custom properties.                                               |
+
+[Back to TOC](README.md)

docs/schema.md

@@ -15,10 +15,12 @@ In ODCS v3, the schema has evolved from the table and column representation, the
 
 Figure 1 illustrates those terms with a basic relational database.
 
-<img src=../img/elements-of-schema-odcs-v3.svg width=600/>
+<img src=../img/elements-of-schema-odcs-v3.png width=600/>
 
 *Figure 1: elements of the schema in ODCS v3.*
 
+[Back to TOC](README.md)
+
 ## Examples
 
 ### Complete schema
@@ -277,3 +279,5 @@ schema:
       - "2024-03-10T14:22:35Z"
 
 ```
+
+[Back to TOC](README.md)

docs/service-level-agreement.md

@@ -11,6 +11,8 @@ This section describes the service-level agreements (SLA).
 * Separate multiple object.element by a comma, as in `table1.col1`, `table2.col1`, `table1.col2`.
 * If there is only one object in the contract, the object name is not required.
 
+[Back to TOC](README.md)
+
 ## Example
 
 ```YAML
@@ -74,3 +76,5 @@ Recommend SLA properties follow the [Data QoS periodic table](https://medium.com
 * `timeToDetect` (synonym `td`) - time to detect an issue.
 * `timeToNotify` (synonym `tn`).
 * `timeToRepair` (synonym `tr`).
+
+[Back to TOC](README.md)

docs/support-communication-channels.md

@@ -7,6 +7,8 @@ description: "Support and communication channels help consumers find help regard
 
 Support and communication channels help consumers find help regarding their use of the data contract.
 
+[Back to TOC](README.md)
+
 ## Examples
 
 ### Minimal example
@@ -57,3 +59,6 @@ support:
 | support.scope            | Scope             | No       | Scope can be: `interactive`, `announcements`, `issues`, `notifications`.                                                            |
 | support.invitationUrl    | Invitation URL    | No       | Some tools uses invitation URL for requesting or subscribing. Follows the [URL scheme](https://en.wikipedia.org/wiki/URL#Syntax).   |
 | support.customProperties | Custom Properties | No       | Any custom properties.                                                                                                              |
+
+[Back to TOC](README.md)
+

docs/team.md

@@ -9,7 +9,9 @@ This section lists team members and the history of their relation with this data
 > [!NOTE]
 > In v2.x, this section was called `stakeholders`. Starting with v3.1.0, both the following structure are valid. However, the original v2.x / v3.x structure is deprecated and will be removed in ODCS v4. 
 
-The structure describing "team" is shared between all Bitol standards, matching RFC 0016.
+The structure describing `team` is shared between all Bitol standards, matching RFC 0016.
+
+[Back to TOC](README.md)
 
 ##  Example
 
@@ -92,3 +94,4 @@ The UX label is the label used in the UI and other user experiences.
 | team.dateOut            | Date Out             | No       | The date when the user ceased to be part of the team.                                      |
 | team.replacedByUsername | Replaced By Username | No       | The username of the user who replaced the previous user.                                   |
 
+[Back to TOC](README.md)