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