Merge pull request #11 from Open-Data-Product-Initiative/datacontract

Added data contract element
Open-Data-Product-Initiative · Jul 15, 2024 · ca98577 · ca98577
2 parents b2aac38 + 593018b
commit ca98577
Show file tree

Hide file tree

Showing 3 changed files with 130 additions and 4 deletions.
diff --git a/source/examples/DataContract/datacontract-inline.yml b/source/examples/DataContract/datacontract-inline.yml
@@ -0,0 +1,67 @@
+schema: https://opendataproducts.org/dev/schema/odps.yaml
+version: 3.0
+product:
+
+  contract:
+    id: 02323M123  
+    type:  DCS 
+    contractVersion:  0.9.3
+    spec: 
+      id: urn:datacontract:checkout:orders-latest
+      info:
+        title: Orders Latest
+        version: 1.0.0
+        description: |
+          Successful customer orders in the webshop. 
+          All orders since 2020-01-01. 
+          Orders with their line items are in their current state (no history included).
+        owner: Checkout Team
+        slackChannel: "#checkout"
+        contact:
+          name: John Doe (Data Product Owner)
+          url: https://teams.microsoft.com/l/channel/example/checkout
+      tags:
+        - checkout
+        - orders
+        .... CUT OFF FOR SAKE OF SPACE....
+
+  details: 
+    en:
+      name: Pets of the year
+      productID: 123456are
+      valueProposition: Design a customised petstore using a data product that describes
+        pets with their habits, preferences and characteristics.
+      description: This is an example of a Petstore product.
+      productSeries: Lovely pets data products
+      visibility: private
+      status: draft
+      productVersion: '0.1.0'
+      versionNotes: New version with additional details such more accurate pet details
+      issues: The current issues include incorrect information in the dog breeds. The
+        resolution for these problems is planned for the next     update, scheduled
+        to be released on July 15th, 2023.
+      categories:
+      - pets
+      standards:
+      - ISO 24631-6
+      tags:
+      - pet
+      brandSlogan: Passion for the data monetization
+      type: dataset
+      contentSample: https://download.com/pets.json
+      logoURL: https://data-product-business.github.io/open-data-product-spec/images/logo-dps-ebd5a97d.png
+      OutputFileFormats:
+      - JSON
+      - XML
+      - CSV
+      - ZIP
+      - PDF
+      useCases:
+      - useCase:
+          useCaseTitle: Build attractive and lucrative petstore!
+          useCaseDescription: Use case description how succesfull petstore chain was
+            established in Abu Dhabi
+          useCaseURL: https://marketplace.com/usecase1
+      recommendedDataProducts:
+      - https://marketplace.com/dataproduct.json
+      - https://marketplace.com/dataproduct-another.json
diff --git a/source/examples/DataContract/datacontract-url.yml b/source/examples/DataContract/datacontract-url.yml
@@ -0,0 +1,48 @@
+schema: https://opendataproducts.org/dev/schema/odps.yaml
+version: 3.0
+product:
+  contract:
+    id: 02323M123  
+    type:  ODCS 
+    contractVersion:  2.2.2
+    contractURL: https://demo.datamesh-manager.com/demo834016807886/dataproducts/9bd53b1b-b51e-41a8-a757-4d33b4cde460
+  details: 
+    en:
+      name: Pets of the year
+      productID: 123456are
+      valueProposition: Design a customised petstore using a data product that describes
+        pets with their habits, preferences and characteristics.
+      description: This is an example of a Petstore product.
+      productSeries: Lovely pets data products
+      visibility: private
+      status: draft
+      productVersion: '0.1.0'
+      versionNotes: New version with additional details such more accurate pet details
+      issues: The current issues include incorrect information in the dog breeds. The
+        resolution for these problems is planned for the next     update, scheduled
+        to be released on July 15th, 2023.
+      categories:
+      - pets
+      standards:
+      - ISO 24631-6
+      tags:
+      - pet
+      brandSlogan: Passion for the data monetization
+      type: dataset
+      contentSample: https://download.com/pets.json
+      logoURL: https://data-product-business.github.io/open-data-product-spec/images/logo-dps-ebd5a97d.png
+      OutputFileFormats:
+      - JSON
+      - XML
+      - CSV
+      - ZIP
+      - PDF
+      useCases:
+      - useCase:
+          useCaseTitle: Build attractive and lucrative petstore!
+          useCaseDescription: Use case description how succesfull petstore chain was
+            established in Abu Dhabi
+          useCaseURL: https://marketplace.com/usecase1
+      recommendedDataProducts:
+      - https://marketplace.com/dataproduct.json
+      - https://marketplace.com/dataproduct-another.json
diff --git a/source/index.html.md b/source/index.html.md
@@ -161,9 +161,9 @@ product:
 | **en** | element | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) defined 2-letter codes | **REQUIRED** - **NOTE! This is a dynamic element!** This element binds together other product attributes and expresses the langugage used. In the example this is "en", which indicates that product details are in English. If you would like to use French details, then name the element "fr". The naming of this element follows options (language codes) listed in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard. <br/><br/> You can have product details in multiple languages simply by adding similar sets like the example - just change the binding element name to matching language code. <br/><br/> The pattern to implement multilanguage support for data products was adopted from de facto UI translation practices. The attributes inside this element are commonly rendered in the UI for the consumer and providing a simple way to implement that was the driving reasoning. See for example  [JSON - Multi Language](https://simplelocalize.io/docs/file-formats/multi-language-json/) |
 | **name** | string | max length 256 chars | **REQUIRED** The name of the product. |
 | **productID**  | string | max length 256 chars | **REQUIRED** Product identifier. |
-| **visibility**  | one of | one of: private, invitation, organisation, dataspace, public | **REQUIRED** The publicity level eg who can see this product. Private - just the creator. Invitation - visible only to parties explicitly invited. Organisation - visible to all in your organisation. Dataspace - visible to all existent members of the data space. Public - visible to all publicly. |
-| **status**  | one of | one of: announcement, draft, development, testing, acceptance, production, sunset, retired | **REQUIRED** The status of the product. Lifecycle model discussed in details in here (link). |
-| **type** | one of |  Options: raw data, derived data, dataset, reports, analytic view, 3D visualisation, algorithm, decision support, automated decision-making, data-enhanced product, data-driven service, data-enabled performance, bi-directional. | **REQUIRED** The type of the product. Options are derived from examples and lists found from academic literature.  | 
+| **visibility**  | string | one of: private, invitation, organisation, dataspace, public | **REQUIRED** The publicity level eg who can see this product. Private - just the creator. Invitation - visible only to parties explicitly invited. Organisation - visible to all in your organisation. Dataspace - visible to all existent members of the data space. Public - visible to all publicly. |
+| **status**  | string | one of: announcement, draft, development, testing, acceptance, production, sunset, retired | **REQUIRED** The status of the product. Lifecycle model discussed in details in here (link). |
+| **type** | string |  one of: raw data, derived data, dataset, reports, analytic view, 3D visualisation, algorithm, decision support, automated decision-making, data-enhanced product, data-driven service, data-enabled performance, bi-directional. | **REQUIRED** The type of the product. Options are derived from examples and lists found from academic literature.  | 
 
 
 ## Optional attributes
@@ -178,6 +178,11 @@ RecommendedUseCases **OBJECT** is an array which contains offers method to attac
 schema: https://opendataproducts.org/v3.0rc/schema/odps.yaml
 version: 3.0
 product:
+  contract:
+    id: 02323M123  
+    type:  ODCS 
+    contractVersion:  2.2.2
+    contractURL: https://demo.datamesh-manager.com/demo834016807886/dataproducts/9bd53b1b-b51e-41a8-a757-4d33b4cde460
   details: 
     en:
       name: Pets of the year
@@ -223,6 +228,12 @@ product:
 
 | <div style="width:150px">Element name</div>   | Type  | Options  | Description  |
 |---|---|---|---|
+| **contract**  | element | - | Binds together data contract details. You can use both URL and inline (YAML) for data contract content. | 
+| **id**  | string | - | UUID of the data contract | 
+| **type**  | string | one of: ODCS, DCS | Defines the standard used in data contract. Currently supported options: [ODCS](https://github.com/bitol-io/open-data-contract-standard) and [DCS](https://datacontract.com/). | 
+| **contractVersion**  | string | - | Version of the standard used to define the Data Contract. Type attribute defines the standard/specification. NOTE! This is not the possible iterated version of the data contract itself. | 
+| **contractURL**  | URL | Valid URL. See more from [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). | URL pointing to data contract in data contract management service or alike. Optionally you can use _spec_ to add data contract details as YAML inline element. | 
+| **spec**  | string | YAML | Inline YAML element to add data contract details instead of using URL. | 
 | **created**  | date | Use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | When product was created. | 
 | **updated**  | date | Use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | When product was last updated. |
 | **valueProposition** | string  | text content, max length 512 chars  | This is the product's value proposition. Often one or two sentences and crystallizes the value for the customer. |
@@ -240,7 +251,7 @@ product:
 | **brandSlogan** | string | - | Brand related slogan like Nike has *just do it*. |
 | **useCases** | element | array | Contains list of related use cases with description information and link to details. **NOTE!** These examples are expected to use same language as defined previously in the data product details content binding element. |
 | **useCaseTitle**| string | string | Title of the usecase. |
-| **useCaseDescription** | string | string | Brief description of the usecase. |
+| **useCaseDescription** | string | - | Brief description of the usecase. |
 | **useCaseURL**| URL | Valid URL, [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) | Valid URL of the more detailed usecase description. |
 | **recommendedDataProducts** | array | Array of valid URLs ([RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)) | Data products to recommend use next to this data product or even as replacement (for comparison). The URL provided MUST reference a description of a data product following this same standard |