Fortschritt

Teil D · Datenplattformoptional

Übung 9 · Semantik

Fachliche Begriffe einmal definieren und deine Kontrakte damit verknüpfen.

~25 Min.0 von 5 Schritten erledigt

Jeder deiner Kontrakte hat eine eigene Kopie der Beschreibungen von order_id, order_total und sku. Und eine Beschreibung sagt, was ein Feld enthält, nicht welcher fachliche Begriff es ist. Hier definierst du jeden Begriff einmal, in einer Ontologie-Datei mit stabilen IRIs, lädst sie in einem Rutsch hoch und verknüpfst die Kontrakte aus der letzten Übung damit.

Das lernst du

Eine fachliche Ontologie als eine Datei schreiben: Entitäten, Properties, Beziehungen
Begriffe mit IRIs identifizieren, die auf jeder Plattform-Instanz funktionieren
Felder im Kontrakt per authoritativeDefinitions mit Begriffen verknüpfen
„Welche Datenprodukte enthalten X?“ per Rückwärtssuche beantworten

Die Ontologie schreiben

Ontologie-Datei schreiben

Lege semantics.yaml im Wurzelverzeichnis des Repositorys an. Sie enthält den kompletten Namespace ecommerce:

prefixes deklariert ecom: als Kurzform der IRI-Basis, sodass jeder Begriff iri: ecom:Order schreiben kann.
Begriffe vom Typ EntityType sind die Geschäftsobjekte (Order, Article). Begriffe vom Typ ValueType sind ihre Properties (Order ID, Order Total, SKU).
Beziehungen vom Typ hasProperty hängen Properties an Entitäten. Beziehungen vom Typ relatedTo verbinden Entitäten: Eine Bestellung enthält Artikel.

semantics.yaml

version: 0.2.0.dev0
name: ecommerce
description: Business concepts of the e-commerce platform.
custom_properties:
  display_name: E-Commerce
prefixes:
  ecom: https://learn.datacontract.com/ontology/ecommerce#
ontology:
  - concept: Order
    id: order
    type: EntityType
    description: A customer order in the e-commerce platform.
    iri: ecom:Order
    relationships:
      - id: order_has_order_id
        name: order_id
        type: hasProperty
        roles:
          - concept: Order ID
      - id: order_has_order_total
        name: order_total
        type: hasProperty
        roles:
          - concept: Order Total
      - id: order_contains_article
        name: contains
        type: relatedTo
        description: An order contains one or more articles.
        roles:
          - concept: Article
        verbalizes:
          - "{Order} contains {Article}"
  - concept: Article
    id: article
    type: EntityType
    description: A product that can be bought in the e-commerce platform.
    iri: ecom:Article
    relationships:
      - id: article_has_sku
        name: sku
        type: hasProperty
        roles:
          - concept: SKU
  - concept: Order ID
    id: order_id
    type: ValueType
    description: Unique identifier of an order (UUID).
    iri: ecom:orderId
  - concept: Order Total
    id: order_total
    type: ValueType
    description: Total amount of an order in cents, never negative.
    iri: ecom:orderTotal
  - concept: SKU
    id: sku
    type: ValueType
    description: Stock keeping unit, the unique identifier of an article.
    iri: ecom:sku

In einem Rutsch hochladen

Ein einziges PUT ersetzt den ganzen Namespace durch die Datei: Es legt den Namespace, alle Begriffe und alle Beziehungen in der richtigen Reihenfolge an. Die Entropy Data CLI hat dafür noch keinen Befehl, deshalb rufst du die API direkt auf. Sie nutzt denselben API Key und Host wie die CLI:

curl -sS -f -X PUT "$ENTROPY_DATA_HOST/api/semantics/experimental/namespaces/ecommerce/ontology.yaml" \
  -H "x-api-key: $ENTROPY_DATA_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @semantics.yaml -w "HTTP %{http_code}\n"

HTTP 200

Unter Windows gibt ein erfolgreicher Aufruf nichts aus.

Community Edition

Das Setup-Skript hat ENTROPY_DATA_API_KEY und ENTROPY_DATA_HOST in die .env geschrieben, aber curl und Invoke-RestMethod lesen diese Datei nicht. Lade die beiden Werte zuerst in deine Shell:

set -a; source .env; set +a

Prüfe, was angekommen ist:

entropy-data semantics concepts list ecommerce

               semantic-concepts (page 0)
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┓
┃ ID          ┃ Name        ┃ Kind     ┃ Group ┃ Status ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━┩
│ article     │ Article     │ entity   │       │        │
│ order       │ Order       │ entity   │       │        │
│ order_id    │ Order ID    │ property │       │        │
│ order_total │ Order Total │ property │       │        │
│ sku         │ SKU         │ property │       │        │
└─────────────┴─────────────┴──────────┴───────┴────────┘

Später etwas ändern? Bearbeite semantics.yaml und lade sie erneut hoch. Begriffe, die du aus der Datei entfernst, verschwinden auch aus dem Namespace.

Deine Datenkontrakte verknüpfen

Felder per IRI verknüpfen

Verknüpfe Schemas und Felder über authoritativeDefinitions vom Typ semantics mit den Begriffen und nutze die volle IRI als url:

YAML

schema:
  - name: orders
    authoritativeDefinitions:
      - type: semantics
        url: https://learn.datacontract.com/ontology/ecommerce#Order
    properties:
      - name: order_id
        authoritativeDefinitions:
          - type: semantics
            url: https://learn.datacontract.com/ontology/ecommerce#orderId

Mach das für jedes Feld, zu dem es einen Begriff gibt:

Feld	IRI
`order_total`	`https://learn.datacontract.com/ontology/ecommerce#orderTotal`
`sku`	`https://learn.datacontract.com/ontology/ecommerce#sku`

Verknüpfe sie in orders_v1, orders_v2 und sku_sales_per_year. Entferne dann die kopierten Beschreibungen aus diesen Feldern. Die Definition steht jetzt im Begriff.

Prüfe, ob die Kontrakte gültig bleiben:

datacontract lint orders_v1.odcs.yaml
datacontract lint orders_v2.odcs.yaml
datacontract lint sku_sales_per_year.odcs.yaml

╭────────┬────────────────────────────────────────────┬───────┬─────────╮
│ Result │ Check                                      │ Field │ Details │
├────────┼────────────────────────────────────────────┼───────┼─────────┤
│ passed │ Data contract is valid against ODCS v3.2.0 │       │         │
╰────────┴────────────────────────────────────────────┴───────┴─────────╯
🟢 data contract is valid. Run 1 checks. Took 0.17 seconds.
…
🟢 data contract is valid. Run 1 checks. Took 0.17 seconds.
…
🟢 data contract is valid. Run 1 checks. Took 0.14 seconds.

Kontrakte erneut veröffentlichen

entropy-data datacontracts put orders_v1 --file orders_v1.odcs.yaml
entropy-data datacontracts put orders_v2 --file orders_v2.odcs.yaml
entropy-data datacontracts put sku_sales_per_year --file sku_sales_per_year.odcs.yaml

Data contract 'orders_v1' saved.
Open https://app.entropy-data.com/tutorial-simon/datacontracts/orders_v1
Data contract 'orders_v2' saved.
Open https://app.entropy-data.com/tutorial-simon/datacontracts/orders_v2
Data contract 'sku_sales_per_year' saved.
Open https://app.entropy-data.com/tutorial-simon/datacontracts/sku_sales_per_year

Die Ontologie erkunden

Ontologie erkunden

Geh in der Weboberfläche auf Semantics → E-Commerce und öffne Article → SKU:

Das Diagramm zeigt die Ontologie: Order mit ihren Properties, contains, Article mit SKU.
Metadata zeigt die IRI des Begriffs, als ecom:sku und ausgeschrieben.
Data Products ist die Rückwärtssuche: alle Datenprodukte, deren Kontrakte auf den Begriff verweisen. „Welche Datenprodukte enthalten SKUs?“ ist jetzt ein Klick.

Der Begriff SKU: Ontologie-Diagramm, IRI und die Datenprodukte, die ihn nutzen

Auch die Liste der Datenprodukte zeigt die verknüpften Begriffe:

Datenprodukte mit ihren verknüpften Begriffen in der Spalte Semantics

Kurzer Check

Warum verknüpfst du Felder per IRI statt über die URL des Begriffs auf der Plattform?