├── LICENSE ├── README.md ├── examples ├── shipments-odcs.xlsx └── shipments-odcs.yaml └── odcs-template.xlsx /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Data Contract 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Open Data Contract Standard (ODCS) - Excel Template 2 | 3 | This repository contains an [Excel template](https://github.com/datacontract/open-data-contract-standard-excel-template/raw/refs/heads/main/odcs-template.xlsx) for authoring data contracts using the **Open Data Contract Standard V3**. 4 | It provides a user-friendly interface to define and share data contracts with stakeholders, especially those less familiar with YAML. 5 | You can convert the Excel into YAML through the [Data Contract CLI](#data-contract-cli) or upload it directly to [Data Mesh Manager](#data-mesh-manager). 6 | 7 | 8 | image 9 | 10 | 11 | 12 | ## 📥 Template 13 | 14 | Download the Excel Template: 15 | - [odcs-template.xlsx](https://github.com/datacontract/open-data-contract-standard-excel-template/raw/refs/heads/main/odcs-template.xlsx) 16 | 17 | ## 💡 Example 18 | 19 | Here is an example Data Contract: 20 | 21 | - [shipments-example.xlsx](https://github.com/datacontract/open-data-contract-standard-excel-template/raw/refs/heads/main/examples/shipments-odcs.xlsx) that can be converted to [this YAML](https://github.com/datacontract/open-data-contract-standard-excel-template/raw/refs/heads/main/examples/shipments-odcs.yaml) 22 | 23 | 24 | ## 🧾 What is a Data Contract? 25 | 26 | A **data contract**, such as [ODCS](https://bitol-io.github.io/open-data-contract-standard/latest/), defines the structure, format, semantics, quality, and terms of use for data exchanged between a producer and one or more consumers. 27 | 28 | While data contracts are typically written in YAML, this Excel template enables easier collaboration, review, and iteration—especially across business and technical teams. 29 | 30 | 31 | ## 📄 Template Overview 32 | 33 | The Excel file includes the following sheets: 34 | 35 | ### 1. `Instructions` 36 | Provides a quick guide on how to fill out the template. 37 | 38 | ### 2. `Fundamentals` 39 | Captures general metadata for the data contract, including ID, Name, Version, Domain and Description. 40 | 41 | ### 3. `Schema ` 42 | Defines the data model with all properties. 43 | 44 | Copy this sheet for every table in your data contract. 45 | 46 | ### 4. `Support` 47 | 48 | Support and communication channels help consumers find help regarding their use of the data contract. 49 | 50 | ### 5. `Team` 51 | 52 | This section lists team members and the history of their relation with this data contract. In v2.x, this section was called stakeholders. 53 | 54 | ### 6. `Roles` 55 | 56 | This section lists team members and the history of their relation with this data contract. 57 | 58 | ### 7. `SLA` 59 | 60 | This section describes the service-level agreements (SLA). 61 | 62 | ### 8. `Servers` 63 | 64 | The servers element describes where the data protected by this data contract is physically located. 65 | 66 | ### 9. `Pricing` 67 | 68 | This section covers pricing when you bill your customer for using this data product. 69 | 70 | ### 10. `Custom Properties` 71 | 72 | Use this optional sheet to define additional metadata or annotations. 73 | 74 | 75 | ## 🚀 Integrations 76 | 77 | ### Data Contract CLI 78 | Use the open-source [Data Contract CLI](https://github.com/datacontract/datacontract-cli) to convert the Excel template to or from YAML. 79 | 80 | ``` 81 | datacontract import --format excel --source odcs.xlsx 82 | ``` 83 | 84 | ### Data Mesh Manager 85 | 86 | Upload the Excel directly in [Data Mesh Manager](https://datamesh-manager.com) using the “Import Excel” feature, and open existing ODCS data contracts in Excel using the "Open in Excel" feature. 87 | 88 | image 89 | 90 | 91 | ## 📜 License 92 | 93 | Created by [Jochen Christ](https://www.linkedin.com/in/jochenchrist/) and [Dr. Simon Harrer](https://www.linkedin.com/in/simonharrer/) under MIT License 94 | -------------------------------------------------------------------------------- /examples/shipments-odcs.xlsx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/datacontract/open-data-contract-standard-excel-template/2dbbb3d817963a7984e541111b58c79b63ed9107/examples/shipments-odcs.xlsx -------------------------------------------------------------------------------- /examples/shipments-odcs.yaml: -------------------------------------------------------------------------------- 1 | apiVersion: v3.0.0 2 | kind: DataContract 3 | id: fulfillment_shipments_v1 4 | name: Shipments 5 | version: 1.0.0 6 | domain: sales-team 7 | status: draft 8 | tenant: company-A 9 | tags: 10 | - datalocation:EU 11 | description: 12 | purpose: This data can be used for analytical purposes 13 | usage: Use this to analyze shipments 14 | limitations: Not suitable for real-time use cases 15 | authoritativeDefinitions: 16 | - type: Data Guidelines 17 | url: https://example.com/data-guidelines.html 18 | customProperties: 19 | - property: github_link 20 | value: https://github.example.com/shipment-specification.yaml 21 | customProperties: 22 | - property: additionalField 23 | value: some value 24 | - property: owner 25 | value: controlling-team 26 | schema: 27 | - name: shipments 28 | physicalType: table 29 | physicalName: shipments_v1 30 | businessName: Shipments 31 | description: "This table contains shipment data, including details about shipment IDs, associated orders, delivery dates, carriers, tracking numbers, statuses, and additional shipment information in JSON format." 32 | dataGranularityDescription: Not Aggregated 33 | tags: 34 | - pii 35 | quality: 36 | - type: sql 37 | description: Table shall contain at least 1 row 38 | query: SELECT COUNT(*) FROM shipments 39 | thresholdType: mustBeGreaterThanOrEqualTo 40 | mustBeGreaterThanOrEqualTo: 1 41 | properties: 42 | - name: shipment_id 43 | businessName: Shipment ID 44 | physicalName: sid 45 | logicalType: string 46 | description: Unique identifier for each shipment. 47 | required: false 48 | unique: false 49 | physicalType: uuid 50 | primaryKey: true 51 | partitioned: false 52 | classification: internal 53 | examples: 54 | - 123e4567-e89b-12d3-a456-426614174000 55 | criticalDataElement: false 56 | quality: [] 57 | tags: 58 | - businesskey 59 | authoritativeDefinitions: 60 | - type: businessDefinition 61 | url: https://example.com/definitions/shipment_id 62 | - name: order_id 63 | businessName: Order ID 64 | physicalName: oid 65 | logicalType: string 66 | logicalTypeOptions: 67 | minLength: 8 68 | maxLength: 10 69 | description: Identifier for the order associated with the shipment. 70 | required: true 71 | unique: false 72 | physicalType: text 73 | primaryKey: false 74 | partitioned: false 75 | classification: internal 76 | examples: 77 | - ORD12345 78 | criticalDataElement: false 79 | - name: delivery_date 80 | businessName: Delivery Date 81 | logicalType: date 82 | description: The actual or expected delivery date of the shipment. 83 | required: false 84 | unique: false 85 | physicalType: timestamp_tz 86 | primaryKey: false 87 | partitioned: false 88 | classification: internal 89 | examples: 90 | - 2023-10-01T10:00:00Z 91 | criticalDataElement: false 92 | quality: [] 93 | - name: carrier 94 | businessName: Carrier 95 | logicalType: string 96 | description: The shipping carrier used for the delivery. 97 | required: false 98 | unique: false 99 | physicalType: text 100 | primaryKey: false 101 | partitioned: false 102 | classification: internal 103 | examples: 104 | - FedEx 105 | - UPS 106 | criticalDataElement: false 107 | quality: [] 108 | - name: tracking_number 109 | businessName: Tracking Number 110 | logicalType: string 111 | description: Tracking number provided by the carrier. 112 | required: false 113 | unique: false 114 | physicalType: text 115 | primaryKey: false 116 | partitioned: false 117 | classification: restricted 118 | examples: 119 | - 1Z999AA10123456784 120 | criticalDataElement: false 121 | quality: [] 122 | customProperties: 123 | - property: external 124 | value: "true" 125 | - name: status 126 | businessName: Status 127 | logicalType: string 128 | description: Current status of the shipment. 129 | required: false 130 | unique: false 131 | physicalType: text 132 | primaryKey: false 133 | partitioned: false 134 | classification: internal 135 | examples: 136 | - Delivered 137 | - In Transit 138 | criticalDataElement: false 139 | quality: [] 140 | - name: inline_object_definition 141 | businessName: Inline Object Definition 142 | logicalType: object 143 | description: A JSON representation of additional shipment info 144 | required: false 145 | unique: false 146 | physicalType: json 147 | primaryKey: false 148 | partitioned: false 149 | partitionKeyPosition: -1 150 | classification: internal 151 | examples: 152 | - "{\"destination\": \"New York\"}" 153 | criticalDataElement: false 154 | quality: 155 | - type: text 156 | description: "{field} must contain the field \"destination\"" 157 | - name: address 158 | businessName: Shipment Address 159 | logicalType: object 160 | description: Shipping address details. 161 | required: true 162 | physicalType: JSON 163 | classification: restricted 164 | properties: 165 | - name: street 166 | businessName: Street 167 | logicalType: string 168 | description: Street address. 169 | required: true 170 | unique: false 171 | physicalType: text 172 | primaryKey: false 173 | partitioned: false 174 | classification: restricted 175 | examples: 176 | - Marienplatz 1 177 | - name: city 178 | businessName: City 179 | logicalType: string 180 | description: City of the shipping address. 181 | required: true 182 | unique: false 183 | physicalType: text 184 | primaryKey: false 185 | partitioned: false 186 | classification: restricted 187 | examples: 188 | - Munich 189 | - name: country 190 | businessName: Country 191 | logicalType: string 192 | description: Country of the shipping address. 193 | required: true 194 | physicalType: text 195 | primaryKey: false 196 | partitioned: false 197 | classification: restricted 198 | examples: 199 | - DE 200 | servers: 201 | - server: production 202 | type: bigquery 203 | environment: production 204 | dataset: shipments_v1 205 | project: acme_shipments_prod 206 | support: 207 | - channel: slackname 208 | url: http://find.me.here 209 | tool: slack 210 | scope: interactive 211 | authoritativeDefinitions: 212 | - type: Guidelines 213 | url: https://example.com/guidelines 214 | price: 215 | priceAmount: 1 216 | priceCurrency: EUR 217 | priceUnit: Per 1000 requests 218 | team: 219 | - username: vimportant 220 | role: administrator 221 | dateIn: 2020-01-01 222 | - username: nimportant 223 | role: reader 224 | dateIn: 2020-01-01 225 | dateOut: 2024-10-10 226 | slaProperties: 227 | - property: availability 228 | value: 95% 229 | unit: '%' 230 | driver: operational 231 | -------------------------------------------------------------------------------- /odcs-template.xlsx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/datacontract/open-data-contract-standard-excel-template/2dbbb3d817963a7984e541111b58c79b63ed9107/odcs-template.xlsx --------------------------------------------------------------------------------