From a4e52f1b7e8588f665a6397daa48da5456715ab4 Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:52:55 -0600 Subject: [PATCH 01/13] Enhance navigation with 'Back to TOC' links Added 'Back to TOC' links for easier navigation. --- docs/fundamentals.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/fundamentals.md b/docs/fundamentals.md index 5db1020..9a18443 100644 --- a/docs/fundamentals.md +++ b/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) From 7dd5141f008cea55ea7aa62c18b6167636872254 Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:53:46 -0600 Subject: [PATCH 02/13] Update CHANGELOG for v3.1.0 proposed changes Clarified changes in the specification for version 3.1.0. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2fe12ec..efe3c60 100644 --- a/CHANGELOG.md +++ b/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. From 8f55386cca5d073df9438973cc86fb38f0b6958c Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:55:48 -0600 Subject: [PATCH 03/13] Add TOC link to custom properties section Added a back to TOC link in the custom properties section. --- docs/custom-other-properties.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/custom-other-properties.md b/docs/custom-other-properties.md index 9b671bc..0f8e1f7 100644 --- a/docs/custom-other-properties.md +++ b/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) From 792a22f881524b6ecd69b211fa55cda9c8a7b474 Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:56:12 -0600 Subject: [PATCH 04/13] Enhance navigation with 'Back to TOC' links Added 'Back to TOC' links for improved navigation. --- docs/data-quality.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/data-quality.md b/docs/data-quality.md index a47a572..495dd01 100644 --- a/docs/data-quality.md +++ b/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) + From 53a3a0e0b5e2891014418568335487b4bfcb81e1 Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:56:40 -0600 Subject: [PATCH 05/13] Add 'Back to TOC' links in infrastructure-servers.md --- docs/infrastructure-servers.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/infrastructure-servers.md b/docs/infrastructure-servers.md index 40c5949..387b3a2 100644 --- a/docs/infrastructure-servers.md +++ b/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) From 3bcb0d18c3ab70443ccb6d31542fd0a1b39d452a Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:56:56 -0600 Subject: [PATCH 06/13] Enhance pricing.md with TOC navigation link Added a 'Back to TOC' link to the pricing documentation. --- docs/pricing.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/pricing.md b/docs/pricing.md index 85381e4..d47f65d 100644 --- a/docs/pricing.md +++ b/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) From 45add9f4065b2868de0340f6df634678e336020e Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:57:15 -0600 Subject: [PATCH 07/13] Add 'Back to TOC' links in references.md Added 'Back to TOC' links to references section. --- docs/references.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/references.md b/docs/references.md index 294ae76..8c14860 100644 --- a/docs/references.md +++ b/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) From a5c2e3ef192567974eec95b47cb23e412c377181 Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:58:39 -0600 Subject: [PATCH 08/13] Fix punctuation in roles documentation --- docs/roles.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/roles.md b/docs/roles.md index af4bc8b..60dedf4 100644 --- a/docs/roles.md +++ b/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) From 62856045b757727731241eda4e002473983de32d Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 09:59:37 -0600 Subject: [PATCH 09/13] Change schema image to PNG and add TOC link Updated image format for schema illustration and added back to TOC link. --- docs/schema.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/schema.md b/docs/schema.md index 97ea17c..e9b9900 100644 --- a/docs/schema.md +++ b/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. - + *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) From 8dfb5079c81336e214834db67ce0274daf923c54 Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 10:00:08 -0600 Subject: [PATCH 10/13] Add back to TOC links in service-level-agreement.md --- docs/service-level-agreement.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/service-level-agreement.md b/docs/service-level-agreement.md index 808116d..23c1dcb 100644 --- a/docs/service-level-agreement.md +++ b/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) From d4c3aeb5af3a5bd8fc7f436dc9eec2277ab60618 Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 10:00:37 -0600 Subject: [PATCH 11/13] Enhance support communication channels documentation Added back to TOC links and improved formatting. --- docs/support-communication-channels.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/support-communication-channels.md b/docs/support-communication-channels.md index 61c42cf..60c0bed 100644 --- a/docs/support-communication-channels.md +++ b/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) + From 372c6950045c57670e5c49285f6396789b6b80fa Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 10:01:07 -0600 Subject: [PATCH 12/13] Fix formatting and update team section notes --- docs/team.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/team.md b/docs/team.md index 61242fe..65f79e5 100644 --- a/docs/team.md +++ b/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) From 2f616fad645ce9f0a1f3fd2354ea48787d5401ab Mon Sep 17 00:00:00 2001 From: "Jean-Georges \"jgp\" Perrin" Date: Wed, 3 Dec 2025 10:02:56 -0600 Subject: [PATCH 13/13] Add new book resource to documentation --- docs/resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources.md b/docs/resources.md index 1682a5d..8ca76b3 100644 --- a/docs/resources.md +++ b/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!