Merge pull request #121 from bitol-io/readme-date-logical

add Expressing Date / Datetime / Timezone information to readme

Author: pflooky

README.md

@@ -13,7 +13,7 @@ Welcome!
 Thanks for your interest and for taking the time to come here! ❤️
 
 ## Executive summary
-This standard describes a structure for a **data contract**. Its current version is v3.0.0. It is available for you as an Apache 2.0 license. Contributions are welcome!
+This standard describes a structure for a **data contract**. Its current version is v3.0.1. It is available for you as an Apache 2.0 license. Contributions are welcome!
 
 ## Discover the open standard
 A reader-friendly version of the standard can be found on its [dedicated site](https://bitol-io.github.io/open-data-contract-standard/).

docs/README.md

@@ -289,6 +289,53 @@ Additional metadata options to more accurately define the data type.
 | string         | minLength        | Minimum Length     | No       | Minimum length of the string.                                                                                                                                                                         |
 | string         | pattern          | Pattern            | No       | Regular expression pattern to define valid value. Follows regular expression syntax from ECMA-262 (https://262.ecma-international.org/5.1/#sec-15.10.1).                                              |
 
+#### Expressing Date / Datetime / Timezone information
+
+Given the complexity of handling various date and time formats (e.g., date, datetime, time, timestamp, timestamp with and without timezone), the existing `logicalType` options currently support only `date`. To specify additional temporal details, `logicalType` should be used in conjunction with `logicalTypeOptions.format`  or `physicalType` to define the desired format. Using `physicalType` allows for definition of your data-source specific data type.  
+
+``` yaml
+version: 1.0.0
+kind: DataContract
+id: 53581432-6c55-4ba2-a65f-72344a91553a
+status: active
+name: date_example
+apiVersion: v3.0.1
+schema:
+  # Date Only 
+  - name: event_date
+    logicalType: date
+    logicalTypeOptions:
+      - format: "yyyy-MM-dd"
+    examples:
+      - "2024-07-10"
+
+  # Date & Time (UTC)  
+  - name: created_at
+    logicalType: date
+    logicalTypeOptions:
+      - format: "yyyy-MM-ddTHH:mm:ssZ"
+    examples:
+      - "2024-03-10T14:22:35Z"
+
+  # Time Only 
+  - name: event_start_time
+    logicalType: date
+    logicalTypeOptions:
+      - format: "HH:mm:ss"
+    examples:
+      - "08:30:00"
+
+    # Physical Type with Date & Time (UTC)
+  - name: event_date
+    logicalType: date
+    physicalType: DATETIME
+    logicalTypeOptions:
+      - format: yyyy-MM-ddTHH:mm:ssZ"
+    examples:
+      - "2024-03-10T14:22:35Z"
+
+```
+
 ### Authoritative definitions
 
 Reference to an external definition on element logic or values.

vendors.md

@@ -7,7 +7,7 @@ Vendors who natively support ODCS (Open Data Contract Standard).
 A non-exhaustive, alphabetical list of organizations offering solutions natively compatible with ODCS, such as data
 catalogs, data quality platforms, security tools, and more.
 
-* [Data Caterer](https://data.catering/setup/guide/data-source/metadata/open-data-contract-standard/) - Test data
+* [Data Caterer](https://data.catering/latest/docs/guide/data-source/metadata/open-data-contract-standard/) - Test data
   management tool using data contracts as a metadata source
 * [Data Contract CLI](https://cli.datacontract.com) - Open Source tooling around data contracts
 * [Data Contract Manager](https://datacontract-manager.com) - Professional data contract management tool with Data Marketplace, Access Management, and Data Governance AI.
@@ -19,4 +19,5 @@ catalogs, data quality platforms, security tools, and more.
 ## Service providers
 
 * [AbeaData](https://abeadata.com) - Consulting & training on data contracts.
+* [Andrew Jones](https://andrew-jones.com) Independant consulting & training on data contracts.