Merge pull request #104 from pflooky/prepare-release-v3.0.1

Create new JSON schema for v3.0.1, update changelog, update examples …
bitol-io · Jan 8, 2025 · e645ae9 · e645ae9
2 parents 58d932e + e375f66
commit e645ae9
Show file tree

Hide file tree

Showing 24 changed files with 2,404 additions and 31 deletions.
diff --git a/.github/workflows/validate-examples.yaml b/.github/workflows/validate-examples.yaml
@@ -1,5 +1,7 @@
 name: validate-examples
 on:
+  pull_request:
+    branches: ["*"]
   push:
     branches: ["*"]
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,16 @@ image: "https://raw.githubusercontent.com/bitol-io/artwork/main/horizontal/color
 
 This document tracks the history and evolution of the **Open Data Contract Standard**.
 
+# v3.0.1 - 2024-12-22 - APPROVED
+
+* Added field `authoritativeDefinitions` into JSON schema
+* Added field `description.customProperties`  into JSON schema
+* Added field `description.authoritativeDefinitions`  into JSON schema
+* Added field `role.customProperties`  into JSON schema
+* Updated `status` field to include examples
+* Updated `authoritativeDefinitions` description to be vendor agnostic
+* Updated `tags` description and included examples
+
 # v3.0.0 - 2024-10-21 - APPROVED
 
 * **New section**: Support & communication channels.

diff --git a/docs/README.md b/docs/README.md
@@ -43,7 +43,7 @@ This section contains general information about the contract.
 ### Example
 
 ```YAML
-apiVersion: v3.0.0 # Standard version
+apiVersion: v3.0.1 # Standard version
 kind: DataContract
 
 id: 53581432-6c55-4ba2-a65f-72344a91553a
@@ -66,16 +66,16 @@ tags: ['finance']
 
 | Key                                  | UX label                  | Required | Description                                                                                                                                                                                |
 |--------------------------------------|---------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| apiVersion                           | Standard version          | Yes      | Version of the standard used to build data contract. Default value is `v3.0.0`.                                                                                                            |
+| apiVersion                           | Standard version          | Yes      | Version of the standard used to build data contract. Default value is `v3.0.1`.                                                                                                            |
 | kind                                 | Kind                      | Yes      | The kind of file this is. Valid value is `DataContract`.                                                                                                                                   |
 | id                                   | ID                        | Yes      | A unique identifier used to reduce the risk of dataset name collisions, such as a UUID.                                                                                                    |
 | name                                 | Name                      | No       | Name of the data contract.                                                                                                                                                                 |
 | version                              | Version                   | Yes      | Current version of the data contract.                                                                                                                                                      |
-| status                               | Status                    | Yes      | Current status of the data contract. Examples are "proposed", "draft", "active", "deprecated", "retired".                                                                                                                                                      |
+| status                               | Status                    | Yes      | Current status of the data contract. Examples are "proposed", "draft", "active", "deprecated", "retired".                                                                                  |
 | tenant                               | Tenant                    | No       | Indicates the property the data is primarily associated with. Value is case insensitive.                                                                                                   |
 | domain                               | Domain                    | No       | Name of the logical data domain.                                                                                                                                                           |
 | dataProduct                          | Data Product              | No       | Name of the data product.                                                                                                                                                                  |
-| authoritativeDefinitions | Authoritative Definitions | No       | List of links to sources that provide more details on the data contract.                                                                                                                   |
+| authoritativeDefinitions             | Authoritative Definitions | No       | List of links to sources that provide more details on the data contract.                                                                                                                   |
 | description                          | Description               | No       | Object containing the descriptions.                                                                                                                                                        |
 | description.purpose                  | Purpose                   | No       | Intended purpose for the provided data.                                                                                                                                                    |
 | description.limitations              | Limitations               | No       | Technical, compliance, and legal limitations for data use.                                                                                                                                 |
@@ -218,14 +218,13 @@ schema:
 
 #### Applicable to Elements (either Objects or Properties)
 
-
 | Key                      | UX label                     | Required | Description                                                                                                                                                                                                                   |
 |--------------------------|------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | name                     | Name                         | Yes      | Name of the element.                                                                                                                                                                                                          |
 | physicalName             | Physical Name                | No       | Physical name.                                                                                                                                                                                                                |
 | description              | Description                  | No       | Description of the element.                                                                                                                                                                                                   |
 | businessName             | Business Name                | No       | The business name of the element.                                                                                                                                                                                             |
-| authoritativeDefinitions | Authoritative Definitions    | No       | List of links to sources that provide more details on the table; examples would be a link to an external definition, a training video, a GitHub repo, Collibra, or another tool. See `authoritativeDefinitions` below.        |
+| authoritativeDefinitions | Authoritative Definitions    | No       | List of links to sources that provide more details on the element; examples would be a link to privacy statement, terms and conditions, license agreements, data catalog, or another tool.                                    |
 | quality                  | Quality                      | No       | List of data quality attributes.                                                                                                                                                                                              |
 | tags                     | Tags                         | No       | A list of tags that may be assigned to the elements (object or property); the tags keyword may appear at any level. Tags may be used to better categorize an element. For example, `finance`, `sensitive`, `employee_record`. |
 | customProperties         | Custom Properties            | No       | Custom properties that are not part of the standard.                                                                                                                                                                          |
@@ -648,7 +647,7 @@ roles:
 | roles.access               | Access              | No       | The type of access provided by the IAM role.                         |
 | 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.                                               |
+| roles.customProperties     | Custom Properties   | No       | Any custom properties.                                               |
 
 
 ## Service-Level Agreement (SLA)

diff --git a/docs/examples/all/full-example.odcs.yaml b/docs/examples/all/full-example.odcs.yaml
@@ -11,12 +11,12 @@ description:
   limitations: Data based on seller perspective, no buyer information
   usage: Predict sales over time
   authoritativeDefinitions:
-    type: privacy-statement
-    url: https://example.com/gdpr.pdf
+    - type: privacy-statement
+      url: https://example.com/gdpr.pdf
 tenant: ClimateQuantumInc
 
 kind: DataContract
-apiVersion: v3.0.0 # Standard version (follows semantic versioning)
+apiVersion: v3.0.1 # Standard version (follows semantic versioning)
 
 # Infrastructure & servers
 servers:

diff --git a/docs/examples/data-types/all-data-types.odcs.yaml b/docs/examples/data-types/all-data-types.odcs.yaml
@@ -4,7 +4,7 @@ id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active
 name: my_table
 dataProduct: my_quantum
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 schema:
   - name: transactions_tbl
     description: Provides core payment metrics

diff --git a/docs/examples/fundamentals/table-column-description.odcs.yaml b/docs/examples/fundamentals/table-column-description.odcs.yaml
@@ -3,7 +3,7 @@ kind: DataContract
 id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active
 name: my_quantum
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 schema:
   - name: tbl
     description: Provides core payment metrics

diff --git a/docs/examples/quality/column-accuracy.odcs.yaml b/docs/examples/quality/column-accuracy.odcs.yaml
@@ -4,7 +4,7 @@ id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active
 name: my_table
 dataProduct: my_quantum
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 schema:
   - name: Air_Quality
     description: Air quality of the city of New York

diff --git a/docs/examples/quality/column-completeness.odcs.yaml b/docs/examples/quality/column-completeness.odcs.yaml
@@ -1,5 +1,5 @@
 version: 1.0.0
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active

diff --git a/docs/examples/quality/column-custom.odcs.yaml b/docs/examples/quality/column-custom.odcs.yaml
@@ -1,5 +1,5 @@
 version: 1.0.0
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active

diff --git a/docs/examples/quality/column-validity.odcs.yaml b/docs/examples/quality/column-validity.odcs.yaml
@@ -1,5 +1,5 @@
 version: 1.0.0
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active

diff --git a/docs/examples/roles/service-and-operational-roles.odcs.yaml b/docs/examples/roles/service-and-operational-roles.odcs.yaml
@@ -5,7 +5,7 @@ status: active
 name: my_table
 dataProduct: my_quantum
 schema: []
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 roles:
   - role: microstrategy_user_opr
     access: read

diff --git a/docs/examples/schema/all-schema-types.odcs.yaml b/docs/examples/schema/all-schema-types.odcs.yaml
@@ -3,7 +3,7 @@ kind: DataContract
 id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active
 name: my_quantum
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 schema:
   - name: tbl
     logicalType: object

diff --git a/docs/examples/schema/kafka-schema.odcs.yaml b/docs/examples/schema/kafka-schema.odcs.yaml
@@ -1,4 +1,4 @@
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: orders
 status: development

diff --git a/docs/examples/schema/kafka-schemaregistry.odcs.yaml b/docs/examples/schema/kafka-schemaregistry.odcs.yaml
@@ -1,4 +1,4 @@
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: orders
 status: production

diff --git a/docs/examples/schema/table-column.odcs.yaml b/docs/examples/schema/table-column.odcs.yaml
@@ -4,7 +4,7 @@ id: 53581432-6c55-4ba2-a65f-72344a91553b
 status: active
 name: my_table
 dataProduct: my_quantum
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 schema:
   - name: tbl
     physicalType: table

diff --git a/docs/examples/schema/table-columns-with-partition.odcs.yaml b/docs/examples/schema/table-columns-with-partition.odcs.yaml
@@ -4,7 +4,7 @@ id: 53581432-6c55-4ba2-a65f-72344a91553c
 status: active
 name: my_table
 dataProduct: my_quantum
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 schema:
   - name: tbl
     physicalType: table

diff --git a/docs/examples/server/azure-server.odcs.yaml b/docs/examples/server/azure-server.odcs.yaml
@@ -1,5 +1,5 @@
 version: 1.0.0
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: abc123
 status: in development

diff --git a/docs/examples/server/kafka-server.odcs.yaml b/docs/examples/server/kafka-server.odcs.yaml
@@ -1,5 +1,5 @@
 version: 1.0.0
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: abc123
 status: in development

diff --git a/docs/examples/sla/database-table-sla.odcs.yaml b/docs/examples/sla/database-table-sla.odcs.yaml
@@ -1,5 +1,5 @@
 version: 1.0.0
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active

diff --git a/docs/examples/stakeholders/basic-four-dpo.odcs.yaml b/docs/examples/stakeholders/basic-four-dpo.odcs.yaml
@@ -1,5 +1,5 @@
 version: 1.0.0
-apiVersion: v3.0.0
+apiVersion: v3.0.1
 kind: DataContract
 id: 53581432-6c55-4ba2-a65f-72344a91553a
 status: active

diff --git a/schema/odcs-json-schema-latest.json b/schema/odcs-json-schema-latest.json
@@ -16,9 +16,9 @@
     },
     "apiVersion": {
       "type": "string",
-      "default": "v3.0.0",
-      "description": "Version of the standard used to build data contract. Default value is v3.0.0.",
-      "enum": ["v3.0.0", "v2.2.2", "v2.2.1", "v2.2.0"]
+      "default": "v3.0.1",
+      "description": "Version of the standard used to build data contract. Default value is v3.0.1.",
+      "enum": ["v3.0.1", "v3.0.0", "v2.2.2", "v2.2.1", "v2.2.0"]
     },
     "id": {
       "type": "string",

diff --git a/schema/odcs-json-schema-v3.0.0.json b/schema/odcs-json-schema-v3.0.0.json
@@ -1901,7 +1901,7 @@
     },
     "Tags": {
       "type": "array",
-      "description": "A list of tags that may be assigned to the elements (object or property); the tags keyword may appear at any level. Tags may be used to better categorize an element. For example, `finance`, `sensitive`, `employee_record`.",
+      "description": "A list of tags that may be assigned to the elements (object or property); the tags keyword may appear at any level.",
       "items": {
         "type": "string"
       }