From b90df10a78c5c9608d839c7d2cf7730bef3ecf13 Mon Sep 17 00:00:00 2001 From: tonys Date: Thu, 29 Jan 2026 16:49:38 +0000 Subject: [PATCH 01/10] Add dprod-contracts folder with data contract ontology files Adds DPROD contract TTL files (ontology, shapes, examples), documentation, and supporting files. Co-Authored-By: Claude Opus 4.5 --- dprod-contracts/DATA-CONTRACTS.md | 742 +++++++++++ dprod-contracts/README.md | 49 + .../docs/ODCS-DPROD-Comparison-Report.md | 586 +++++++++ dprod-contracts/docs/display.html | 126 ++ dprod-contracts/dprod-contract-examples.ttl | 632 +++++++++ dprod-contracts/dprod-contracts-shapes.ttl | 560 ++++++++ dprod-contracts/dprod-contracts.ttl | 1132 +++++++++++++++++ dprod-contracts/requirements.txt | 4 + 8 files changed, 3831 insertions(+) create mode 100644 dprod-contracts/DATA-CONTRACTS.md create mode 100644 dprod-contracts/README.md create mode 100644 dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md create mode 100644 dprod-contracts/docs/display.html create mode 100644 dprod-contracts/dprod-contract-examples.ttl create mode 100644 dprod-contracts/dprod-contracts-shapes.ttl create mode 100644 dprod-contracts/dprod-contracts.ttl create mode 100644 dprod-contracts/requirements.txt diff --git a/dprod-contracts/DATA-CONTRACTS.md b/dprod-contracts/DATA-CONTRACTS.md new file mode 100644 index 0000000..d9b7232 --- /dev/null +++ b/dprod-contracts/DATA-CONTRACTS.md @@ -0,0 +1,742 @@ +# DPROD Data Contracts Extension + +## Overview + +**Data Contracts** are formal agreements between data providers and consumers that specify commitments about data quality, delivery schedules, schemas, and usage restrictions. The DPROD Data Contracts extension builds on [ODRL (Open Digital Rights Language)](https://www.w3.org/TR/odrl-model/) to create machine-readable, enforceable agreements for internal organizational data sharing. + +### What is a Data Contract? + +A data contract is a bilateral agreement between two parties: +- **Provider** (assigner): The team or system that produces and delivers the data +- **Consumer** (assignee): The team or system that receives and uses the data + +Unlike legal contracts, data contracts focus on **technical commitments**: +- When will data be delivered? (timeliness) +- What schema must the data conform to? (structure) +- How will changes be communicated? (governance) +- How may the data be used? (restrictions) + +### Why Data Contracts? + +Data contracts address common organizational challenges: + +| Problem | Contract Solution | +|---------|------------------| +| "The daily report is late again" | **Timeliness Promise** with delivery schedule | +| "They changed the schema and broke our pipeline" | **Schema Promise** with SHACL validation + change notification | +| "We can't use this data for compliance reasons" | **Usage Restrictions** with consumer promises | +| "No one told us they were deprecating this API" | **Termination Notice Promise** with notice period | + +### How DPROD Implements Data Contracts + +DPROD extends ODRL with: + +1. **Promise-based commitments**: Providers make promises to deliver quality data; consumers make promises about appropriate use +2. **Temporal modeling**: Schedules (iCalendar RRULE), effective periods, notice periods +3. **Schema integration**: Links to SHACL shapes, OWL ontologies, or industry standards +4. **Lifecycle management**: Contract status (Pending → Active → Expired/Cancelled) +5. **Provenance tracking**: How contracts derive from offers and evolve over time + +--- + +## Quick Start: Core Pattern + +### Simple Example (JSON-LD) + +Here's a minimal data contract showing the essential pattern: + +```json +{ + "@context": { + "dprod": "https://ekgf.github.io/dprod/", + "dcat": "http://www.w3.org/ns/dcat#", + "odrl": "http://www.w3.org/ns/odrl/2/", + "xsd": "http://www.w3.org/2001/XMLSchema#" + }, + "@id": "https://example.com/contract/daily-sales", + "@type": "dprod:DataContract", + + "odrl:assigner": { + "@id": "https://example.com/team/sales-ops", + "rdfs:label": "Sales Operations Team" + }, + + "odrl:assignee": { + "@id": "https://example.com/team/finance", + "rdfs:label": "Finance Team" + }, + + "odrl:target": { + "@id": "https://example.com/dataset/daily-sales", + "@type": "dcat:Dataset", + "rdfs:label": "Daily Sales Dataset" + }, + + "dprod:providerPromise": { + "@type": "dprod:ProviderTimelinessPromise", + "rdfs:label": "Deliver by 8am daily", + "odrl:action": "dprod:fulfill", + "dprod:hasSchedule": { + "@type": "dprod:ICalSchedule", + "dprod:icalRule": "FREQ=DAILY;BYHOUR=8;BYMINUTE=0" + } + }, + + "dprod:contractStatus": "dprod:ContractStatusActive", + + "dprod:hasEffectivePeriod": { + "@type": "time:Interval", + "time:hasBeginning": "2025-01-01T00:00:00Z", + "time:hasEnd": "2025-12-31T23:59:59Z" + } +} +``` + +**What this says:** +- Sales Ops promises to deliver the daily sales dataset to Finance +- Delivery happens daily at 8am UTC +- The contract is active for calendar year 2025 + +--- + +## Architecture Overview + +### Class Hierarchy (Mermaid Diagram) + +```mermaid +graph TD + A[odrl:Policy] --> B[odrl:Offer] + A --> C[odrl:Agreement] + B --> D[dprod:DataOffer] + C --> E[dprod:DataContract] + C --> F[dprod:DataSubscription] + + G[odrl:Rule] --> H[dprod:Promise] + H --> I[dprod:ProviderPromise] + H --> J[dprod:ConsumerPromise] + + I --> K[dprod:ProviderTimelinessPromise] + I --> L[dprod:ProviderSchemaPromise] + I --> M[dprod:ProviderTerminationNoticePromise] + + N[dcat:Dataset] -.target.-> E + N -.target.-> D + O[dcat:DataService] -.target.-> E + P[dprod:DataProduct] -.target.-> E + + E -.providerPromise.-> I + E -.consumerPromise.-> J + + style D fill:#e1f5ff + style E fill:#ffe1e1 + style F fill:#ffe1e1 + style H fill:#fff4e1 + style I fill:#e1ffe1 + style J fill:#ffe1f5 +``` + +### Key Relationships + +| From | Property | To | Meaning | +|------|----------|-----|---------| +| DataContract | `odrl:assigner` | Party | Who provides the data | +| DataContract | `odrl:assignee` | Party | Who consumes the data | +| DataContract | `odrl:target` | Dataset/DataService | What data is governed | +| DataContract | `dprod:providerPromise` | ProviderPromise | Provider's commitments | +| DataContract | `dprod:consumerPromise` | ConsumerPromise | Consumer's obligations | +| ProviderSchemaPromise | `dprod:requiresConformanceTo` | SHACL Shape | Required schema | +| ProviderTimelinessPromise | `dprod:hasSchedule` | Schedule | Delivery schedule | + +--- + +## Main Classes + +### dprod:DataContract + +**Definition**: A bilateral agreement between a data provider and consumer specifying mutual commitments. + +**Extends**: `odrl:Agreement`, `prov:Entity` + +**Required Properties**: +- `odrl:assigner` — The provider party +- `odrl:assignee` — The consumer party +- `odrl:target` — The governed data asset (Dataset, DataService, or DataProduct) + +**Common Properties**: +- `dprod:providerPromise` — Provider commitments (1 or more) +- `dprod:consumerPromise` — Consumer obligations (0 or more) +- `dprod:hasEffectivePeriod` — When the contract is valid (`time:Interval`) +- `dprod:contractStatus` — Lifecycle status (Pending, Active, Expired, Cancelled) +- `dcat:version` — Contract version number +- `dprod:supersedes` — Previous contract this replaces +- `dprod:amends` — Base contract this extends + +**Example**: +```json +{ + "@id": "https://example.com/contract/ml-training-2025", + "@type": "dprod:DataContract", + "odrl:assigner": "https://example.com/team/data-eng", + "odrl:assignee": "https://example.com/team/ml-ops", + "odrl:target": "https://example.com/dataset/clickstream", + "dprod:providerPromise": [ + { "@id": "#schema-freeze" }, + { "@id": "#daily-8am" } + ], + "dprod:contractStatus": "dprod:ContractStatusActive" +} +``` + +--- + +### dprod:ProviderPromise + +**Definition**: A commitment made by the data provider about quality, timeliness, or governance. + +**Extends**: `odrl:Rule` (disjoint with Duty, Permission, Prohibition) + +**Required Properties**: +- `odrl:action` — Must be `dprod:fulfill` + +**Subclasses**: +- `dprod:ProviderTimelinessPromise` — Delivery schedule commitments +- `dprod:ProviderSchemaPromise` — Schema conformance guarantees +- `dprod:ProviderTerminationNoticePromise` — Advance notice of changes/termination + +--- + +### dprod:ProviderTimelinessPromise + +**Definition**: Promise about when data will be delivered or updated. + +**Key Property**: +- `dprod:hasSchedule` — Schedule object (iCalendar RRULE or schema.org Schedule) + +**Example**: +```json +{ + "@type": "dprod:ProviderTimelinessPromise", + "rdfs:label": "Hourly refresh", + "odrl:action": "dprod:fulfill", + "dprod:hasSchedule": { + "@type": "dprod:ICalSchedule", + "dprod:icalRule": "FREQ=HOURLY;INTERVAL=1" + } +} +``` + +**Common Schedules**: +- Daily at 6am: `FREQ=DAILY;BYHOUR=6;BYMINUTE=0` +- Every 5 minutes: `FREQ=MINUTELY;INTERVAL=5` +- Weekly on Monday: `FREQ=WEEKLY;BYDAY=MO` +- Quarterly: Use `schema:Schedule` with `schema:repeatFrequency "P3M"` + +--- + +### dprod:ProviderSchemaPromise + +**Definition**: Promise that data will conform to a specified schema or standard. + +**Key Properties**: +- `odrl:target` — The specific dataset this promise applies to +- `dprod:requiresConformanceTo` — The schema (SHACL shape, OWL ontology, or industry standard) + +**Example**: +```json +{ + "@type": "dprod:ProviderSchemaPromise", + "rdfs:label": "Customer schema stability", + "odrl:action": "dprod:fulfill", + "odrl:target": "https://example.com/dataset/customers", + "dprod:requiresConformanceTo": { + "@id": "https://example.com/shape/customer-v2", + "@type": ["sh:NodeShape", "dct:Standard"], + "rdfs:label": "Customer Schema V2" + } +} +``` + +This pattern enables **automated validation**: the provider can validate data against the SHACL shape before delivery, ensuring contract compliance. + +--- + +### dprod:ProviderTerminationNoticePromise + +**Definition**: Promise to give advance notice before terminating a contract or introducing breaking changes. + +**Key Properties**: +- `odrl:action` — Must be `dprod:issueNotice` +- `dprod:noticePeriod` — Required lead time (`time:Interval`) + +**Example**: +```json +{ + "@type": "dprod:ProviderTerminationNoticePromise", + "rdfs:label": "90-day change notice", + "odrl:action": "dprod:issueNotice", + "dprod:noticePeriod": { + "@type": "time:Interval", + "rdfs:comment": "90 days advance notice required" + } +} +``` + +This prevents surprise breaking changes that disrupt downstream consumers. + +--- + +### dprod:ConsumerPromise + +**Definition**: A commitment made by the data consumer about how they will use the data. + +**Required Properties**: +- `odrl:action` — Typically `dprod:performCompliantUse` + +**Example**: +```json +{ + "@type": "dprod:ConsumerPromise", + "rdfs:label": "Marketing use only", + "rdfs:comment": "Data may only be used for campaign targeting, not credit decisions", + "odrl:action": "dprod:performCompliantUse" +} +``` + +Common consumer promises: +- **Usage restrictions**: "Only for fraud detection, not marketing" +- **Retention policies**: "Delete after 90 days per GDPR" +- **Rate limits**: "Max 1000 API calls per minute" +- **Access controls**: "Provide read-only access to external auditors" + +--- + +## Usage Patterns + +### Pattern 1: Schema Validation Guarantee + +**Scenario**: Data Engineering promises ML team that clickstream data will conform to a stable schema for the entire year. + +**Contract** (simplified): +```json +{ + "@context": { + "dprod": "https://ekgf.github.io/dprod/", + "dcat": "http://www.w3.org/ns/dcat#", + "odrl": "http://www.w3.org/ns/odrl/2/", + "sh": "http://www.w3.org/ns/shacl#", + "xsd": "http://www.w3.org/2001/XMLSchema#" + }, + + "@id": "https://example.com/contract/ml-clickstream-2025", + "@type": "dprod:DataContract", + + "rdfs:label": "ML Training Clickstream Contract 2025", + + "odrl:assigner": { + "@id": "https://example.com/team/data-eng", + "rdfs:label": "Data Engineering" + }, + + "odrl:assignee": { + "@id": "https://example.com/team/ml-ops", + "rdfs:label": "ML Operations" + }, + + "odrl:target": { + "@id": "https://example.com/dataset/clickstream-training", + "@type": "dcat:Dataset", + "dcat:title": "Clickstream Training Dataset" + }, + + "dprod:providerPromise": { + "@type": "dprod:ProviderSchemaPromise", + "rdfs:label": "Schema Freeze for 2025", + "rdfs:comment": "No breaking changes to ClickStreamV2 schema during 2025", + "odrl:action": "dprod:fulfill", + "odrl:target": "https://example.com/dataset/clickstream-training", + + "dprod:requiresConformanceTo": { + "@id": "https://example.com/shape/clickstream-v2", + "@type": ["sh:NodeShape", "dct:Standard"], + "rdfs:label": "ClickStream V2 Schema", + + "sh:property": [ + { + "sh:path": "ex:userId", + "sh:datatype": "xsd:string", + "sh:minCount": 1, + "sh:pattern": "^[a-f0-9]{64}$", + "rdfs:comment": "SHA-256 hashed user ID" + }, + { + "sh:path": "ex:timestamp", + "sh:datatype": "xsd:dateTime", + "sh:minCount": 1 + }, + { + "sh:path": "ex:eventType", + "sh:datatype": "xsd:string", + "sh:in": ["page_view", "click", "purchase"] + } + ] + } + }, + + "dprod:hasEffectivePeriod": { + "@type": "time:Interval", + "time:hasBeginning": "2025-01-01T00:00:00Z", + "time:hasEnd": "2025-12-31T23:59:59Z" + }, + + "dprod:contractStatus": "dprod:ContractStatusActive" +} +``` + +**Value**: ML team can train models knowing the schema won't change mid-year and break production pipelines. + +--- + +### Pattern 2: Timeliness with Daily Schedule + +**Scenario**: Finance promises Marketing that customer segmentation data will refresh daily at 6am UTC. + +**Contract** (simplified): +```json +{ + "@context": { + "dprod": "https://ekgf.github.io/dprod/", + "dcat": "http://www.w3.org/ns/dcat#", + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + + "@id": "https://example.com/contract/customer-segments-2025", + "@type": "dprod:DataContract", + + "rdfs:label": "Customer Segmentation Contract", + + "odrl:assigner": "https://example.com/dept/finance", + "odrl:assignee": "https://example.com/dept/marketing", + "odrl:target": "https://example.com/dataset/customer-segments", + + "dprod:providerPromise": [ + { + "@type": "dprod:ProviderTimelinessPromise", + "rdfs:label": "Daily 6am refresh", + "odrl:action": "dprod:fulfill", + "dprod:hasSchedule": { + "@type": "dprod:ICalSchedule", + "dprod:icalRule": "FREQ=DAILY;BYHOUR=6;BYMINUTE=0", + "rdfs:comment": "Daily at 06:00 UTC" + } + }, + { + "@type": "dprod:ProviderSchemaPromise", + "rdfs:label": "Segment schema guarantee", + "odrl:action": "dprod:fulfill", + "odrl:target": "https://example.com/dataset/customer-segments", + "dprod:requiresConformanceTo": "https://example.com/shape/customer-segment" + } + ], + + "dprod:consumerPromise": { + "@type": "dprod:ConsumerPromise", + "rdfs:label": "Campaign use only", + "rdfs:comment": "Marketing may only use for campaign targeting, not credit decisions", + "odrl:action": "dprod:performCompliantUse" + } +} +``` + +**Value**: Marketing knows exactly when data arrives for their 9am campaign launches. Finance commits to not changing the schema without notice. + +--- + +### Pattern 3: Privacy-Safe Data with Validation + +**Scenario**: Product Analytics promises Personalization team that user behavior data will be privacy-safe (PII removed, GDPR-compliant). + +**Contract** (simplified): +```json +{ + "@context": { + "dprod": "https://ekgf.github.io/dprod/", + "dcat": "http://www.w3.org/ns/dcat#", + "odrl": "http://www.w3.org/ns/odrl/2/", + "sh": "http://www.w3.org/ns/shacl#" + }, + + "@id": "https://example.com/contract/user-behavior-personalization", + "@type": "dprod:DataContract", + + "odrl:assigner": "https://example.com/team/product-analytics", + "odrl:assignee": "https://example.com/team/personalization", + "odrl:target": "https://example.com/dataset/user-events", + + "dprod:providerPromise": { + "@type": "dprod:ProviderSchemaPromise", + "rdfs:label": "Privacy-safe events", + "rdfs:comment": "All PII removed before delivery - safe for ML use", + "odrl:action": "dprod:fulfill", + "odrl:target": "https://example.com/dataset/user-events", + + "dprod:requiresConformanceTo": { + "@id": "https://example.com/shape/privacy-compliant-events", + "@type": ["sh:NodeShape", "dct:Standard"], + "rdfs:label": "Privacy-Compliant Events Shape", + "rdfs:comment": "Enforces PII removal via SHACL validation", + + "sh:property": [ + { + "sh:path": "ex:userId", + "sh:pattern": "^[a-f0-9]{64}$", + "rdfs:comment": "Must be SHA-256 hash, not plaintext" + }, + { + "sh:path": "ex:eventType", + "sh:in": ["page_view", "product_click", "add_to_cart"] + } + ], + + "sh:not": [ + { "sh:path": "ex:email" }, + { "sh:path": "ex:ipAddress" }, + { "sh:path": "ex:phoneNumber" } + ], + + "rdfs:comment": "Validation fails if email, IP, or phone present - acts as privacy firewall" + } + }, + + "dprod:consumerPromise": { + "@type": "dprod:ConsumerPromise", + "rdfs:label": "GDPR deletion compliance", + "rdfs:comment": "Honor deletion requests within 30 days, retrain models without deleted users", + "odrl:action": "dprod:performCompliantUse" + } +} +``` + +**Value**: The SHACL shape acts as a **privacy firewall** — data fails validation if PII leaks through. Personalization team can use the data confidently for ML. + +--- + +### Pattern 4: Change Notification with Termination Notice + +**Scenario**: Sales Ops provides API access to Customer Success team with a 90-day notice requirement before breaking changes. + +**Contract** (simplified): +```json +{ + "@context": { + "dprod": "https://ekgf.github.io/dprod/", + "dcat": "http://www.w3.org/ns/dcat#", + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + + "@id": "https://example.com/contract/customer-account-api", + "@type": "dprod:DataContract", + + "odrl:assigner": "https://example.com/team/sales-ops", + "odrl:assignee": "https://example.com/team/customer-success", + + "odrl:target": { + "@id": "https://example.com/service/customer-account-api", + "@type": "dcat:DataService", + "dcat:title": "Customer Account API v2" + }, + + "dprod:providerPromise": [ + { + "@type": "dprod:ProviderSchemaPromise", + "rdfs:label": "API v2 stability", + "rdfs:comment": "API follows semantic versioning - v2 stays stable", + "odrl:action": "dprod:fulfill", + "odrl:target": "https://example.com/service/customer-account-api", + "dprod:requiresConformanceTo": "https://example.com/spec/customer-api-v2-openapi" + }, + { + "@type": "dprod:ProviderTerminationNoticePromise", + "rdfs:label": "90-day deprecation notice", + "odrl:action": "dprod:issueNotice", + "dprod:noticePeriod": { + "@type": "time:Interval", + "rdfs:comment": "Minimum 90 days notice before v2 deprecation or breaking changes" + } + } + ], + + "dprod:consumerPromise": { + "@type": "dprod:ConsumerPromise", + "rdfs:label": "Rate limit compliance", + "rdfs:comment": "Max 1000 requests/minute - enforced by API gateway", + "odrl:action": "dprod:performCompliantUse" + } +} +``` + +**Value**: Customer Success team can build integrations confidently knowing they'll get 90 days to migrate before v3 or breaking changes. + +--- + +## Contract Lifecycle + +Contracts progress through statuses: + +```mermaid +stateDiagram-v2 + [*] --> Pending: Contract created + Pending --> Active: Effective period starts + Active --> Expired: Natural end date reached + Active --> Cancelled: Early termination + Expired --> [*] + Cancelled --> [*] +``` + +**Status Vocabulary** (`dprod:ContractStatus`): +- `dprod:ContractStatusPending` — Negotiation or awaiting effective date +- `dprod:ContractStatusActive` — Currently in force +- `dprod:ContractStatusExpired` — Reached natural end date +- `dprod:ContractStatusCancelled` — Terminated before planned end + +**Contract Versioning**: +- `dprod:supersedes` — This contract replaces a previous version (old becomes Expired/Cancelled) +- `dprod:amends` — This contract extends/modifies a base contract (both remain Active) + +**Example** (renewal): +```json +{ + "@id": "https://example.com/contract/2025-renewal", + "@type": "dprod:DataContract", + "dprod:supersedes": "https://example.com/contract/2024", + "dcat:version": "2.0", + "rdfs:comment": "2025 renewal with updated SLAs" +} +``` + +--- + +## Integration with DPROD Data Products + +Data contracts naturally integrate with DPROD Data Products: + +```json +{ + "@id": "https://example.com/product/customer-360", + "@type": "dprod:DataProduct", + "dcat:title": "Customer 360 Data Product", + + "odrl:hasPolicy": { + "@id": "https://example.com/offer/customer-360-standard", + "@type": "dprod:DataOffer", + "rdfs:comment": "Standing offer - anyone can request access" + }, + + "dprod:dataContract": [ + { + "@id": "https://example.com/contract/finance-customer-360", + "@type": "dprod:DataContract", + "odrl:assignee": "https://example.com/dept/finance", + "rdfs:comment": "Finance's active contract" + }, + { + "@id": "https://example.com/contract/marketing-customer-360", + "@type": "dprod:DataContract", + "odrl:assignee": "https://example.com/dept/marketing", + "rdfs:comment": "Marketing's active contract" + } + ] +} +``` + +This allows a single data product to have: +- **One offer** (the standard terms available to anyone) +- **Many contracts** (executed agreements with specific consumers) + +--- + +## Best Practices + +### 1. Start Simple +Begin with minimal contracts containing just timeliness or schema promises. Add complexity as needed. + +### 2. Make Schemas Machine-Readable +Use SHACL shapes (not just comments) so providers can validate data before delivery: +```bash +# Validate data before delivery +pyshacl --shacl customer-shape.ttl --data-file daily-export.ttl +``` + +### 3. Use iCalendar for Schedules +[RFC 5545 RRULE](https://icalendar.org/iCalendar-RFC-5545/3-3-10-recurrence-rule.html) is widely supported: +- Libraries: Python `dateutil.rrule`, JavaScript `rrule.js` +- Clear semantics: `FREQ=DAILY;BYHOUR=8` is unambiguous + +### 4. Version Your Contracts +Use `dcat:version` and provenance properties (`supersedes`, `amends`) to track evolution. + +### 5. Automate Monitoring +Build monitors that check: +- Is data arriving on schedule? (timeliness promise) +- Does data validate against the shape? (schema promise) +- Are notice periods being honored? (termination promise) + +### 6. Link to Governance +Embed contracts in your data catalog (DCAT) and governance tools. Contracts are *metadata* that should be discoverable. + +--- + +## Namespace Declarations + +For JSON-LD contexts: + +```json +{ + "@context": { + "dprod": "https://ekgf.github.io/dprod/", + "dcat": "http://www.w3.org/ns/dcat#", + "dct": "http://purl.org/dc/terms/", + "odrl": "http://www.w3.org/ns/odrl/2/", + "prov": "http://www.w3.org/ns/prov#", + "skos": "http://www.w3.org/2004/02/skos/core#", + "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "time": "http://www.w3.org/2006/time#", + "sh": "http://www.w3.org/ns/shacl#", + "schema": "http://schema.org/" + } +} +``` + +For Turtle: +```turtle +@prefix dprod: . +@prefix dcat: . +@prefix dct: . +@prefix odrl: . +@prefix prov: . +@prefix time: . +@prefix sh: . +``` + +--- + +## Further Reading + +- **ODRL Information Model**: https://www.w3.org/TR/odrl-model/ +- **DCAT3 Specification**: https://www.w3.org/TR/vocab-dcat-3/ +- **SHACL**: https://www.w3.org/TR/shacl/ +- **PROV-O**: https://www.w3.org/TR/prov-o/ +- **iCalendar RRULE**: https://icalendar.org/iCalendar-RFC-5545/3-3-10-recurrence-rule.html +- **DPROD Specification**: https://ekgf.github.io/dprod/ + +--- + +## Appendix: Complete Example + +See [`dprod-contract-examples.ttl`](./dprod-contract-examples.ttl) for comprehensive Turtle examples demonstrating: +- Finance → Marketing customer segmentation contract +- Data Engineering → ML Ops training data contract +- Sales → Customer Success API access contract +- Accounting → Audit quarterly SOX compliance contract +- Product Analytics → Personalization privacy-safe events contract +- Contract lifecycle and versioning patterns diff --git a/dprod-contracts/README.md b/dprod-contracts/README.md new file mode 100644 index 0000000..0adaa0d --- /dev/null +++ b/dprod-contracts/README.md @@ -0,0 +1,49 @@ +# DPROD Data Contracts Ontology + +A semantic web ontology for formalizing **Data Contracts** - bilateral agreements between data providers and consumers using W3C standards. + +## Overview + +DPROD Data Contracts models: +- **DataContract** - Binding agreement between provider and consumer +- **DataOffer** - Provider's proposal for data access +- **Provider Promises** - Timeliness, schema conformance, change notification +- **Consumer Promises** - Usage restrictions, retention policies + +Built on: RDF, OWL, SHACL, ODRL, DCAT + +## Files + +| File | Purpose | +|------|---------| +| `dprod-contracts.ttl` | Core ontology (classes, properties) | +| `dprod-contracts-shapes.ttl` | SHACL validation shapes | +| `dprod-contract-examples.ttl` | Example instances | + +## Quick Start + +```bash +# Install dependencies +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt + +# Validate examples against shapes +pyshacl -s dprod-contracts-shapes.ttl -df turtle dprod-contract-examples.ttl +``` + +## Documentation + +- [DATA-CONTRACTS.md](DATA-CONTRACTS.md) - Full specification and usage patterns +- [CLAUDE.md](CLAUDE.md) - Design philosophy and development guide +- [AGENTS.md](AGENTS.md) - Contribution guidelines + +## Related + +- [DPROD (Data Product Ontology)](https://ekgf.github.io/dprod/) - Parent ontology +- [DCAT](https://www.w3.org/TR/vocab-dcat-3/) - W3C Data Catalog Vocabulary +- [ODRL](https://www.w3.org/TR/odrl-model/) - Open Digital Rights Language + +## License + +MIT diff --git a/dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md b/dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md new file mode 100644 index 0000000..6ae533d --- /dev/null +++ b/dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md @@ -0,0 +1,586 @@ +# DPROD Data Contract Ontology: Comparison Report + +**Comparison with Open Data Contract Standard (ODCS)** + +| | | +|---|---| +| **Date** | 2025-12-19 | +| **Version** | DPROD v9.0 vs ODCS v3.1 | +| **Purpose** | Design validation through use case comparison | +| **Verdict** | **Feature Complete** - Full parity with ODCS | + +--- + +## 1. Executive Summary + +This report evaluates the DPROD Data Contract Ontology by comparing its capabilities against the Open Data Contract Standard (ODCS), a widely-adopted YAML-based specification maintained by the Linux Foundation's Bitol project. + +### Key Findings + +| Category | DPROD Assessment | +|----------|------------------| +| **Rights & Obligations** | Superior - ODRL-based policy language | +| **Versioning & Provenance** | Superior - Rich semantic relationships | +| **Schema Handling** | Equivalent - Different approach (reference vs inline) | +| **SLA Metrics** | Equivalent - Quantitative targets with measurement periods | +| **Data Quality Rules** | Simplified - Promise-based with descriptive text | +| **Support Channels** | Superior - Structured channels with response times | +| **Infrastructure** | Acceptable - Appropriately abstracted | +| **Pricing** | Equivalent - schema.org integration | + +### Recommendation + +The DPROD ontology is **feature complete** for both internal organizational data sharing and external marketplace scenarios. + +--- + +## 2. Standards Compared + +### DPROD Data Contract Ontology +- **Format**: RDF/Turtle (Semantic Web) +- **Foundation**: W3C vocabularies (ODRL, DCAT, PROV, TIME, ORG) +- **Approach**: Promise-based bilateral agreements +- **Validation**: SHACL shapes +- **Target Use**: Internal and external data sharing with quantitative SLAs + +### Open Data Contract Standard (ODCS) +- **Format**: YAML +- **Foundation**: Custom schema with JSON Schema validation +- **Approach**: Document-centric specification +- **Validation**: JSON Schema +- **Target Use**: General data contracts (internal and external) + +--- + +## 3. Use Case Analysis + +### 3.1 Schema Definition & Validation + +#### ODCS Approach +```yaml +schema: + - name: customers + physicalName: CUSTOMERS + properties: + - name: customer_id + logicalType: string + physicalType: VARCHAR(50) + required: true + primaryKey: true + classification: internal +``` + +#### DPROD Approach +```turtle +ex:contract dprod:providerPromise [ + a dprod:ProviderSchemaPromise ; + odrl:action dprod:maintainSchema ; + odrl:target ex:customerDataset ; + dprod:requiresConformanceTo ex:CustomerSchema +] . + +ex:CustomerSchema a dct:Standard, sh:NodeShape ; + sh:targetClass ex:Customer ; + sh:property [ sh:path ex:customerId ; sh:minCount 1 ] . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Schema location | External reference | Inline | +| Reusability | High (shared schemas) | Low (duplicated per contract) | +| Validation | SHACL (W3C standard) | JSON Schema | +| Human readability | Lower (RDF syntax) | Higher (YAML) | + +**Verdict**: Different approaches with trade-offs. DPROD's separation of concerns is appropriate for an ontology. + +--- + +### 3.2 Service Level Agreements + +#### ODCS Approach +```yaml +slaProperties: + - property: latency + value: 99.5 + unit: percentage + driver: operational + - property: generalAvailability + value: 99.99 + unit: percentage + - property: endOfSupport + value: 2026-12-31 +``` + +#### DPROD Approach +```turtle +ex:contract dprod:providerPromise [ + a dprod:ProviderServiceLevelPromise ; + rdfs:label "99.9% Availability SLA" ; + dct:description "Provider guarantees 99.9% uptime measured monthly." ; + odrl:action dprod:meetServiceLevel ; + dprod:hasServiceLevelTarget [ + a dprod:ServiceLevelTarget ; + dprod:slaMetric dprod:Availability ; + dprod:targetValue 99.9 ; + dprod:unit "percentage" ; + dprod:measurementPeriod [ + a time:Interval ; + time:hasDuration "P1M"^^xsd:duration + ] + ] , + [ + a dprod:ServiceLevelTarget ; + dprod:slaMetric dprod:ResponseTime ; + dprod:targetValue 500 ; + dprod:unit "milliseconds" ; + dct:description "p95 response time" + ] +] . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Delivery schedules | Strong (iCal support) | Basic | +| Availability metrics | Structured | Structured | +| Latency targets | Structured | Structured | +| Measurement units | Supported | Supported | +| Measurement periods | Supported (time:Interval) | Not supported | +| Metric vocabulary | 5 standard metrics | Custom per contract | + +**Verdict**: Full parity with additional support for measurement periods. + +--- + +### 3.3 Data Quality Rules + +#### ODCS Approach +```yaml +quality: + - dimension: completeness + type: library + metric: nullValues + mustBeLessThan: 5 + unit: percentage + - dimension: accuracy + type: sql + query: "SELECT COUNT(*) FROM ${table} WHERE invalid = true" +``` + +#### DPROD Approach +```turtle +ex:contract dprod:providerPromise [ + a dprod:ProviderPromise ; + rdfs:label "Data Quality Guarantee" ; + dct:description "Provider commits to: (1) 99.5% completeness, (2) <0.1% duplicates, (3) 99.9% validity." ; + odrl:action dprod:maintainQuality +] . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Quality commitment | Promise with descriptive text | Structured metrics | +| Threshold values | Human-readable in description | Machine-readable | +| Validation queries | Not supported (external concern) | SQL templates | +| Complexity | Low | High | +| Flexibility | High (any commitment expressible) | Constrained by schema | + +**Verdict**: DPROD takes a simpler approach - quality commitments are expressed as promises with descriptive text. For machine-readable quality metrics, use W3C DQV directly on datasets. SQL validation queries are appropriately an external concern. + +--- + +### 3.4 Consumer Rights & Restrictions + +#### ODCS Approach +```yaml +roles: + - role: data-consumer + access: read-only + firstLevelApprovers: data-steward +``` + +#### DPROD Approach +```turtle +ex:contract dprod:consumerPromise + [ a dprod:ConsumerPromise ; + rdfs:label "Query Access Only" ; + odrl:action dprod:query ] , + [ a dprod:ConsumerPromise ; + rdfs:label "No External Redistribution" ; + odrl:action dprod:restrictPurpose ] , + [ a dprod:ConsumerPromise ; + rdfs:label "Delete on Contract Expiry" ; + odrl:action dprod:deleteOnExpiry ] . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Access types | Rich vocabulary (query, download, stream) | Basic (read/write) | +| Usage restrictions | Detailed (restrictPurpose, deleteOnExpiry) | Limited | +| Transformation rights | Supported (deriveInsights, aggregate, anonymize) | Not addressed | +| Distribution rights | Supported (redistribute, shareInternally) | Not addressed | + +**Verdict**: DPROD is **significantly stronger** for rights management. + +--- + +### 3.5 Contract Lifecycle & Versioning + +#### ODCS Approach +```yaml +status: active +version: 1.2.0 +``` + +#### DPROD Approach +```turtle +ex:contract2025 a dprod:DataContract ; + dprod:contractStatus dprod:ContractStatusActive ; + dcat:version "2.0" ; + dprod:supersedes ex:contract2024 . + +ex:amendment a dprod:DataContract ; + dprod:amends ex:contract2025 ; + rdfs:comment "Adds GDPR compliance requirements" . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Status vocabulary | Rich (Pending, Active, Expired, Cancelled) | Basic | +| Version numbering | Supported | Supported | +| Replacement tracking | `supersedes` relationship | Not supported | +| Amendment tracking | `amends` relationship | Not supported | +| Provenance | PROV-O integration | Not supported | +| Offer→Contract flow | Two-stage model | Single document | + +**Verdict**: DPROD is **superior** for lifecycle management. + +--- + +### 3.6 Support Channels + +#### ODCS Approach +```yaml +support: + - channel: slack + url: https://company.slack.com/data-support + - channel: email + email: data-support@company.com +``` + +#### DPROD Approach +```turtle +ex:contract dprod:providerPromise [ + a dprod:ProviderSupportPromise ; + rdfs:label "Technical Support Commitment" ; + odrl:action dprod:provideSupport ; + dprod:hasSupportChannel [ + a dprod:SupportChannel ; + dprod:channelType dprod:SlackSupport ; + dprod:channelUrl "https://company.slack.com/data-support"^^xsd:anyURI ; + dprod:supportScope dprod:InteractiveSupport ; + dprod:responseTimeTarget [ time:hours 4 ] + ] , + [ + a dprod:SupportChannel ; + dprod:channelType dprod:TicketSupport ; + dprod:channelUrl "https://jira.company.com/servicedesk"^^xsd:anyURI ; + dprod:supportScope dprod:IssueResolution ; + dprod:responseTimeTarget [ time:hours 24 ] + ] +] . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Channel types | 5 standard types (Email, Slack, Teams, Ticket, Docs) | Custom | +| Channel URL | Supported | Supported | +| Response time targets | Supported (time:Duration) | Not supported | +| Support scope | 4 scope types (Interactive, Issues, Announcements, Self-service) | Not supported | + +**Verdict**: DPROD is **superior** for support channel specification. + +--- + +### 3.7 Pricing (Marketplace Scenarios) + +#### ODCS Approach +```yaml +pricing: + - model: usage + unit: GB + price: 0.05 + currency: USD +``` + +#### DPROD Approach +```turtle +ex:offer a dprod:DataOffer ; + dprod:hasPricing [ + a schema:UnitPriceSpecification ; + schema:price 0.05 ; + schema:priceCurrency "USD" ; + schema:unitText "per GB" ; + schema:referenceQuantity [ + a schema:QuantitativeValue ; + schema:value 1 ; + schema:unitCode "E34" # GB in UN/CEFACT + ] + ] . + +# Alternative: Subscription pricing +ex:offer2 dprod:hasPricing [ + a schema:PriceSpecification ; + schema:price 500 ; + schema:priceCurrency "USD" ; + schema:billingDuration "P1M"^^xsd:duration +] . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Usage-based pricing | Supported (schema:UnitPriceSpecification) | Supported | +| Subscription pricing | Supported (billingDuration) | Limited | +| Currency | Supported | Supported | +| Quantity units | Supported (UN/CEFACT codes) | Custom | +| Standards alignment | schema.org | Custom | + +**Verdict**: Full parity with superior standards alignment via schema.org. + +--- + +### 3.8 Infrastructure Configuration + +#### ODCS Approach +```yaml +servers: + - server: production-warehouse + type: snowflake + account: acme.us-east-1 + database: ANALYTICS + schema: CUSTOMERS +``` + +#### DPROD Approach +```turtle +ex:dataset dcat:distribution [ + a dcat:Distribution ; + dcat:accessURL ; + dcat:mediaType "application/json" +] . +``` + +#### Assessment + +| Aspect | DPROD | ODCS | +|--------|-------|------| +| Abstraction level | High (URL-based) | Low (server-specific) | +| Platform details | Not included | Detailed (Snowflake, BigQuery, etc.) | +| Standards alignment | DCAT (W3C) | Custom | + +**Verdict**: DPROD's abstraction is **appropriate**. Operational infrastructure details belong in deployment configurations, not contracts. + +--- + +## 4. Strengths Summary + +### DPROD Advantages Over ODCS + +1. **Semantic Interoperability** + - Built on W3C standards (ODRL, DCAT, PROV, TIME, ORG) + - Integrates with knowledge graphs and data catalogs + - Machine-interpretable relationships + +2. **Rights Management** + - 15+ consumer action types vs ODCS's basic role model + - Clear separation of permissions vs obligations + - Extensible action hierarchy + +3. **Contract Evolution** + - `supersedes` captures complete replacement + - `amends` captures addendums + - `prov:wasDerivedFrom` tracks acceptance from offers + - Full audit trail capability + +4. **Promise-Based Model** + - Clear bilateral structure (provider promises, consumer promises) + - Cleaner than ODRL's duty/permission/prohibition split + - Self-documenting through action semantics + +5. **Validation Framework** + - SHACL shapes provide executable constraints + - Separable from ontology for flexibility + - Industry-standard tooling support + +6. **Quantitative Commitments** + - Service level targets with measurement periods + - Support channels with response time targets + - Pricing via schema.org integration + +--- + +## 5. Design Scope + +### In Scope + +| Capability | Implementation | +|------------|----------------| +| **Quantitative SLAs** | `ProviderServiceLevelPromise` + `ServiceLevelTarget` | +| **Quality Commitments** | `ProviderPromise` + `maintainQuality` action | +| **Support Channels** | `ProviderSupportPromise` + `SupportChannel` | +| **Pricing** | `hasPricing` + `schema:PriceSpecification` | +| **Rights Management** | 15+ consumer action types | +| **Contract Lifecycle** | `supersedes`, `amends`, status vocabulary | + +### Intentionally Out of Scope + +| Item | Rationale | +|------|-----------| +| **Data Classification** | Dataset metadata - attach to `dcat:Dataset` | +| **Lineage** | Dataset metadata - use PROV-O patterns on datasets | +| **SQL Validation Queries** | Operational concern - belongs in monitoring/quality tools | +| **Infrastructure Details** | Deployment configuration - use DCAT distributions | + +### Design Principles + +1. **Separation of Concerns**: Contracts declare intent; monitoring systems track compliance +2. **Standards Alignment**: W3C vocabularies over custom schemas +3. **Extensibility**: RDF allows adding properties without breaking existing contracts + +--- + +## 6. Validation Verdict + +### Design Decision Review + +| Decision | Validation | +|----------|------------| +| ODRL as foundation | **Correct** - Provides extensible policy framework | +| Promise-based model | **Correct** - Cleaner than duty/permission split | +| DCAT integration | **Correct** - Leverages catalog infrastructure | +| Schema by reference | **Correct** - Enables reuse, separates concerns | +| PROV versioning | **Correct** - Captures real-world contract evolution | +| SHACL validation | **Correct** - Platform-compatible, executable | +| Simplified quality | **Correct** - Promise-based; use DQV on datasets | +| schema.org for pricing | **Correct** - Wide adoption, rich model | + +### Final Assessment + +**The DPROD Data Contract Ontology is feature complete.** + +- Full parity with ODCS for quantitative metrics +- Superior for rights management and lifecycle tracking +- W3C standards alignment throughout +- Suitable for both internal and marketplace scenarios + +--- + +## 7. References + +- [Open Data Contract Standard (ODCS)](https://github.com/bitol-io/open-data-contract-standard) +- [ODCS Documentation](https://bitol-io.github.io/open-data-contract-standard/v3.0.2/) +- [W3C ODRL](https://www.w3.org/TR/odrl-model/) +- [W3C DCAT](https://www.w3.org/TR/vocab-dcat-2/) +- [W3C Data Quality Vocabulary](https://www.w3.org/TR/vocab-dqv/) +- [W3C PROV-O](https://www.w3.org/TR/prov-o/) +- [Schema.org PriceSpecification](https://schema.org/PriceSpecification) + +--- + +## Appendix A: DPROD Action Vocabulary + +### Provider Obligation Actions +| Action | Description | +|--------|-------------| +| `dprod:deliverOnSchedule` | Deliver per agreed schedule | +| `dprod:maintainSchema` | Maintain schema conformance | +| `dprod:maintainQuality` | Maintain data quality standards | +| `dprod:meetServiceLevel` | Meet quantitative SLA targets | +| `dprod:notifyChange` | Notify of breaking changes | +| `dprod:notifyTermination` | Provide termination notice | +| `dprod:provideSupport` | Provide technical support | + +### Consumer Obligation Actions +| Action | Description | +|--------|-------------| +| `dprod:complyWithTerms` | Comply with usage terms | +| `dprod:deleteOnExpiry` | Delete data when contract expires | +| `dprod:reportUsage` | Report usage metrics | +| `dprod:provideAttribution` | Attribute data source | +| `dprod:restrictPurpose` | Restrict to declared purpose | + +### Consumer Access Actions +| Action | Description | +|--------|-------------| +| `dprod:query` | Execute queries against data service | +| `dprod:download` | Download data locally | +| `dprod:stream` | Receive real-time feeds | +| `dprod:access` | General data access | + +### Consumer Transformation Actions +| Action | Description | +|--------|-------------| +| `dprod:deriveInsights` | Create analytics/insights | +| `dprod:aggregate` | Combine with other data | +| `dprod:anonymize` | Remove PII before use | +| `dprod:enrich` | Add value/annotations | + +### Consumer Distribution Actions +| Action | Description | +|--------|-------------| +| `dprod:shareInternally` | Share within organization | +| `dprod:republish` | Publish derived datasets | +| `dprod:redistribute` | Share with third parties | + +--- + +## Appendix B: DPROD Vocabularies + +### SLA Metrics (`dprod:SLAMetricScheme`) +| Metric | Description | +|--------|-------------| +| `dprod:Availability` | Percentage of time service is operational | +| `dprod:Latency` | Time delay in data delivery | +| `dprod:Throughput` | Volume processed per unit time | +| `dprod:ErrorRate` | Percentage of failed requests | +| `dprod:ResponseTime` | Time to respond (p50, p95, p99) | + +### Support Channel Types (`dprod:SupportChannelTypeScheme`) +| Type | Description | +|------|-------------| +| `dprod:EmailSupport` | Email-based support | +| `dprod:SlackSupport` | Slack channel | +| `dprod:TeamsSupport` | Microsoft Teams | +| `dprod:TicketSupport` | Ticket/issue system | +| `dprod:DocumentationSupport` | Self-service docs | + +### Support Scopes (`dprod:SupportScopeScheme`) +| Scope | Description | +|-------|-------------| +| `dprod:InteractiveSupport` | Real-time Q&A | +| `dprod:IssueResolution` | Bug/incident handling | +| `dprod:Announcements` | One-way notifications | +| `dprod:SelfService` | Documentation/FAQ | + +--- + +## Appendix C: Critical Files + +| File | Purpose | Triples | +|------|---------|---------| +| `dprod-contracts.ttl` | Main ontology definitions | 764 | +| `dprod-contracts-shapes.ttl` | SHACL validation shapes | 339 | +| `dprod-contract-examples.ttl` | Usage examples (8 examples) | 380 | diff --git a/dprod-contracts/docs/display.html b/dprod-contracts/docs/display.html new file mode 100644 index 0000000..cf052a0 --- /dev/null +++ b/dprod-contracts/docs/display.html @@ -0,0 +1,126 @@ + + + + DPROD Ontology Interactive Map + + + + + +

🧠 DPROD Ontology Explorer

+
+ Core + Promises + Actions + Status +
+ +
+ + + + \ No newline at end of file diff --git a/dprod-contracts/dprod-contract-examples.ttl b/dprod-contracts/dprod-contract-examples.ttl new file mode 100644 index 0000000..0a21701 --- /dev/null +++ b/dprod-contracts/dprod-contract-examples.ttl @@ -0,0 +1,632 @@ +@prefix dprod: . +@prefix dcat: . +@prefix dct: . +@prefix odrl: . +@prefix prov: . +@prefix skos: . +@prefix rdfs: . +@prefix xsd: . +@prefix time: . +@prefix schema: . +@prefix sh: . +@prefix ex: . + +# ============================================================================== +# DPROD DATA CONTRACT EXAMPLES +# ============================================================================== +# +# Four progressively complex examples: +# 1. Minimal Contract - The simplest possible data contract +# 2. Provider Promises - Timeliness, schema, and notification commitments +# 3. Consumer Permissions - Access, transform, and distribute rights +# 4. Full Lifecycle - Complete contract with offers, subscriptions, versioning +# +# ============================================================================== + + +# ============================================================================== +# EXAMPLE 1: MINIMAL DATA CONTRACT +# ============================================================================== +# +# The simplest possible data contract showing how a DataProduct links to a +# contract governing access to its dataset. +# +# ============================================================================== + +ex:salesDataProduct a dprod:DataProduct ; + rdfs:label "Sales Data Product" ; + dprod:dataContract [ + a dprod:DataContract ; + rdfs:label "Sales Data Contract" ; + odrl:assigner [ a odrl:Party ; rdfs:label "Data Team" ] ; + odrl:assignee [ a odrl:Party ; rdfs:label "Analytics Team" ] ; + dprod:contractStatus dprod:ContractStatusActive + ] . + +# TODO: +# - note this would perhaps make sense the other way round with the contract pointing to the data product + +# ============================================================================== +# EXAMPLE 2: PROVIDER PROMISES +# ============================================================================== +# +# Provider commits to timeliness, schema conformance, and change notifications. +# Shows how to use the provider obligation actions. +# +# ============================================================================== + +# TODO: +# - show the data product with the dataset connected to it +# - look into dct:Standard - do we need that? + +# Parties +ex:FinanceTeam a odrl:Party ; + rdfs:label "Finance Team" . + +ex:ReportingTeam a odrl:Party ; + rdfs:label "Reporting Team" . + +# Assets +ex:revenueDataset a dcat:Dataset ; + rdfs:label "Revenue Dataset" ; + dct:description "Monthly revenue figures by product line" ; + dct:conformsTo [ + a dct:Standard, sh:NodeShape ; + rdfs:label "Revenue Data Schema" ; + sh:targetClass ex:RevenueRecord ; + sh:property [ + sh:path ex:productLine ; + sh:datatype xsd:string ; + sh:minCount 1 + ] ; + sh:property [ + sh:path ex:revenue ; + sh:datatype xsd:decimal ; + sh:minCount 1 + ] ; + sh:property [ + sh:path ex:period ; + sh:datatype xsd:gYearMonth ; + sh:minCount 1 + ] + ] . + +# Contract with Provider Promises +ex:revenueContract a dprod:DataContract ; + rdfs:label "Revenue Data Contract" ; + odrl:assigner ex:FinanceTeam ; + odrl:assignee ex:ReportingTeam ; + odrl:target ex:revenueDataset ; + dprod:contractStatus dprod:ContractStatusActive ; + + dprod:hasEffectivePeriod [ + a time:Interval ; + time:hasBeginning "2025-01-01T00:00:00Z"^^xsd:dateTime ; + time:hasEnd "2025-12-31T23:59:59Z"^^xsd:dateTime + ] ; + + dprod:providerPromise + [ + a dprod:ProviderTimelinessPromise ; + rdfs:label "Daily 6am Delivery" ; + dct:description "Provider commits to deliver fresh revenue data daily at 6:00 AM, ensuring timely availability for morning reports." ; + odrl:action dprod:deliverOnSchedule ; + dprod:hasSchedule [ + a dprod:ICalSchedule ; + dprod:icalRule "FREQ=DAILY;BYHOUR=6;BYMINUTE=0" + ] + ] , + [ + a dprod:ProviderSchemaPromise ; + rdfs:label "Revenue Schema Conformance" ; + dct:description "Provider guarantees all revenue records will conform to the defined schema with required fields: productLine, revenue amount, and time period." ; + odrl:action dprod:maintainSchema ; + odrl:target ex:revenueDataset + ] , + [ + a dprod:ProviderTerminationNoticePromise ; + rdfs:label "30-Day Change Notice" ; + dct:description "Provider will provide at least 30 days advance notice before making any breaking changes to the data structure or terminating the service." ; + odrl:action dprod:notifyTermination ; + dprod:noticePeriod [ + a time:Interval ; + time:hasDuration "P30D"^^xsd:duration + ] + ] . + + +# ============================================================================== +# EXAMPLE 3: CONSUMER PROMISES +# ============================================================================== +# +# Shows how consumer promises express both what the consumer WILL do +# and what they will NOT do. This replaces ODRL permissions/prohibitions +# with a simpler promise-based model. +# +# ============================================================================== + +# Parties +ex:ProductTeam a odrl:Party ; + rdfs:label "Product Team" . + +ex:MLTeam a odrl:Party ; + rdfs:label "ML Team" . + +# Asset +ex:clickstreamDataset a dcat:Dataset ; + rdfs:label "Clickstream Dataset" ; + dct:description "User behavior events for ML training" . + +# Contract with Consumer Promises +ex:mlDataContract a dprod:DataContract ; + rdfs:label "ML Training Data Contract" ; + odrl:assigner ex:ProductTeam ; + odrl:assignee ex:MLTeam ; + odrl:target ex:clickstreamDataset ; + dprod:contractStatus dprod:ContractStatusActive ; + + # All consumer commitments as promises + dprod:consumerPromise + [ + a dprod:ConsumerPromise ; + rdfs:label "Query Access Only" ; + dct:description "Consumer promises to access data only through queries, not bulk downloads, to ensure responsible usage and system performance." ; + odrl:action dprod:query + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "Derive ML Insights" ; + dct:description "Consumer will use clickstream data solely to derive machine learning insights and train models for internal product improvements." ; + odrl:action dprod:deriveInsights + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "No External Redistribution" ; + dct:description "Consumer commits to restrict usage to the declared purpose and will not redistribute or share this data with any external parties." ; + odrl:action dprod:restrictPurpose + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "Attribution in Model Docs" ; + dct:description "Consumer promises to acknowledge the Product Team as the data source in all model documentation and related materials." ; + odrl:action dprod:provideAttribution + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "Delete on Contract Expiry" ; + dct:description "Consumer will permanently delete all copies of the clickstream data when this contract expires or is terminated." ; + odrl:action dprod:deleteOnExpiry + ] . + + +# ============================================================================== +# EXAMPLE 4: FULL CONTRACT LIFECYCLE +# ============================================================================== +# +# Complete example showing: +# - DataOffer (pending acceptance) +# - DataContract (active agreement) +# - Contract versioning (supersedes previous version) +# - All promise types together +# +# ============================================================================== + +# Parties +ex:CustomerDataTeam a odrl:Party ; + rdfs:label "Customer Data Team" . + +ex:MarketingTeam a odrl:Party ; + rdfs:label "Marketing Team" . + +# Asset +ex:customerSegmentDataset a dcat:Dataset ; + rdfs:label "Customer Segments" ; + dct:description "Customer segmentation for campaign targeting" ; + dct:conformsTo ex:CustomerSegmentSchema . + +ex:CustomerSegmentSchema a dct:Standard, sh:NodeShape ; + rdfs:label "Customer Segment Schema" ; + sh:targetClass ex:CustomerSegment ; + sh:property [ + sh:path ex:customerId ; + sh:datatype xsd:string ; + sh:minCount 1 + ] ; + sh:property [ + sh:path ex:segment ; + sh:datatype xsd:string ; + sh:in ( "High-Value" "Mid-Market" "SMB" ) + ] . + +# STAGE 1: Provider publishes an Offer (not yet accepted) +ex:customerSegmentOffer a dprod:DataOffer ; + rdfs:label "Customer Segment Data Offer" ; + odrl:assigner ex:CustomerDataTeam ; + odrl:target ex:customerSegmentDataset ; + dprod:contractStatus dprod:ContractStatusPending ; + + # Provider promises in the offer + dprod:providerPromise + [ + a dprod:ProviderTimelinessPromise ; + rdfs:label "Daily Segment Refresh" ; + dct:description "Customer segments will be refreshed daily at 5:00 AM with the latest categorization based on previous day's activity." ; + odrl:action dprod:deliverOnSchedule ; + dprod:hasSchedule [ + a dprod:ICalSchedule ; + dprod:icalRule "FREQ=DAILY;BYHOUR=5;BYMINUTE=0" + ] + ] , + [ + a dprod:ProviderSchemaPromise ; + rdfs:label "Segment Schema Stability" ; + dct:description "Data structure will remain stable with required fields customerId and segment (High-Value, Mid-Market, or SMB)." ; + odrl:action dprod:maintainSchema ; + odrl:target ex:customerSegmentDataset ; + dprod:requiresConformanceTo ex:CustomerSegmentSchema + ] , + [ + a dprod:ProviderPromise ; + rdfs:label "99.5% Data Completeness" ; + dct:description "At least 99.5% of customer records will have complete segment assignments; any gaps will be clearly flagged." ; + odrl:action dprod:maintainQuality + ] , + [ + a dprod:ProviderChangeNotificationPromise ; + rdfs:label "Schema Change Notifications" ; + dct:description "Marketing team will be notified immediately of any planned schema changes, additions, or modifications to segment categories." ; + odrl:action dprod:notifyChange + ] . + +# STAGE 2: Consumer accepts, creating an active Contract +ex:customerSegmentContract2025 a dprod:DataContract ; + rdfs:label "Customer Segment Contract 2025" ; + dcat:version "2.0" ; + + # Bilateral agreement + odrl:assigner ex:CustomerDataTeam ; + odrl:assignee ex:MarketingTeam ; + odrl:target ex:customerSegmentDataset ; + dprod:contractStatus dprod:ContractStatusActive ; + + # Contract period + dprod:hasEffectivePeriod [ + a time:Interval ; + time:hasBeginning "2025-01-01T00:00:00Z"^^xsd:dateTime ; + time:hasEnd "2025-12-31T23:59:59Z"^^xsd:dateTime + ] ; + + # Versioning: this contract supersedes the 2024 version + dprod:supersedes ex:customerSegmentContract2024 ; + + # Provider promises + dprod:providerPromise + [ + a dprod:ProviderTimelinessPromise ; + rdfs:label "Daily Segment Refresh" ; + dct:description "Customer segments will be refreshed daily at 5:00 AM with the latest categorization based on previous day's activity." ; + odrl:action dprod:deliverOnSchedule ; + dprod:hasSchedule [ + a dprod:ICalSchedule ; + dprod:icalRule "FREQ=DAILY;BYHOUR=5;BYMINUTE=0" + ] + ] , + [ + a dprod:ProviderSchemaPromise ; + rdfs:label "Segment Schema Stability" ; + dct:description "Data structure will remain stable with required fields customerId and segment (High-Value, Mid-Market, or SMB)." ; + odrl:action dprod:maintainSchema ; + odrl:target ex:customerSegmentDataset ; + dprod:requiresConformanceTo ex:CustomerSegmentSchema + ] , + [ + a dprod:ProviderPromise ; + rdfs:label "99.5% Data Completeness" ; + dct:description "At least 99.5% of customer records will have complete segment assignments; any gaps will be clearly flagged." ; + odrl:action dprod:maintainQuality + ] , + [ + a dprod:ProviderChangeNotificationPromise ; + rdfs:label "Schema Change Notifications" ; + dct:description "Marketing team will be notified immediately of any planned schema changes, additions, or modifications to segment categories." ; + odrl:action dprod:notifyChange + ] ; + + # Consumer promises (covers all consumer commitments) + dprod:consumerPromise + [ + a dprod:ConsumerPromise ; + rdfs:label "Campaign Use Only" ; + dct:description "Marketing team commits to using customer segments exclusively for internal campaign targeting and personalization efforts." ; + odrl:action dprod:complyWithTerms + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "Quarterly Usage Reports" ; + dct:description "Marketing will provide quarterly reports detailing how segments were used, campaign reach, and any insights gained." ; + odrl:action dprod:reportUsage + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "Access Segments" ; + dct:description "Marketing team will access customer segment data through approved interfaces and analytics platforms only." ; + odrl:action dprod:access + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "Download for Campaigns" ; + dct:description "Marketing may download segment data to local campaign management tools for targeting purposes." ; + odrl:action dprod:download + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "Share Within Marketing" ; + dct:description "Segment data may be shared among marketing sub-teams (campaigns, analytics, content) but must remain within the marketing organization." ; + odrl:action dprod:shareInternally + ] , + [ + a dprod:ConsumerPromise ; + rdfs:label "No External Redistribution" ; + dct:description "Marketing commits not to share customer segments with external vendors, partners, or third-party platforms." ; + odrl:action dprod:restrictPurpose + ] . + +# Previous contract (now expired) +ex:customerSegmentContract2024 a dprod:DataContract ; + rdfs:label "Customer Segment Contract 2024 (Expired)" ; + dcat:version "1.0" ; + odrl:assigner ex:CustomerDataTeam ; + odrl:assignee ex:MarketingTeam ; + odrl:target ex:customerSegmentDataset ; + dprod:contractStatus dprod:ContractStatusExpired . + + +# ============================================================================== +# EXAMPLE 5: SERVICE LEVEL PROMISE (v9.0) +# ============================================================================== +# +# Demonstrates quantitative SLA commitments with availability, latency, +# and throughput targets. Uses the new ServiceLevelTarget structure. +# +# ============================================================================== + +# Contract with Service Level Promises +ex:apiDataContract a dprod:DataContract ; + rdfs:label "API Data Contract with SLAs" ; + odrl:assigner ex:PlatformTeam ; + odrl:assignee ex:ConsumerTeam ; + odrl:target ex:orderDataset ; + dprod:contractStatus dprod:ContractStatusActive ; + + dprod:providerPromise [ + a dprod:ProviderServiceLevelPromise ; + rdfs:label "99.9% Availability SLA" ; + dct:description "Provider guarantees 99.9% uptime measured monthly, with p95 response times under 500ms." ; + odrl:action dprod:meetServiceLevel ; + dprod:hasServiceLevelTarget [ + a dprod:ServiceLevelTarget ; + dprod:slaMetric dprod:Availability ; + dprod:targetValue 99.9 ; + dprod:unit "percentage" ; + dprod:measurementPeriod [ + a time:Interval ; + time:hasDuration "P1M"^^xsd:duration + ] + ] , + [ + a dprod:ServiceLevelTarget ; + dprod:slaMetric dprod:ResponseTime ; + dprod:targetValue 500 ; + dprod:unit "milliseconds" ; + dct:description "p95 response time" + ] , + [ + a dprod:ServiceLevelTarget ; + dprod:slaMetric dprod:Throughput ; + dprod:targetValue 1000 ; + dprod:unit "requests/second" ; + dct:description "Sustained throughput capacity" + ] + ] . + +ex:PlatformTeam a odrl:Party ; rdfs:label "Platform Team" . +ex:ConsumerTeam a odrl:Party ; rdfs:label "Consumer Team" . +ex:orderDataset a dcat:Dataset ; rdfs:label "Order Dataset" . + + +# ============================================================================== +# EXAMPLE 6: DATA QUALITY PROMISE (v9.0) +# ============================================================================== +# +# Shows quality commitments using simple ProviderPromise with maintainQuality +# action. Quality expectations are expressed in the description text. +# For detailed quality metrics, use W3C DQV directly on your datasets. +# +# ============================================================================== + +ex:qualityContract a dprod:DataContract ; + rdfs:label "Data Quality Contract" ; + odrl:assigner ex:DataEngineeringTeam ; + odrl:assignee ex:AnalyticsTeam ; + odrl:target ex:customerMasterDataset ; + dprod:contractStatus dprod:ContractStatusActive ; + + dprod:providerPromise [ + a dprod:ProviderPromise ; + rdfs:label "Data Quality Guarantee" ; + dct:description "Provider commits to: (1) 99.5% completeness - required fields populated, (2) <0.1% duplicates - unique records maintained, (3) 99.9% validity - records pass validation rules." ; + odrl:action dprod:maintainQuality + ] . + +ex:DataEngineeringTeam a odrl:Party ; rdfs:label "Data Engineering Team" . +ex:AnalyticsTeam a odrl:Party ; rdfs:label "Analytics Team" . +ex:customerMasterDataset a dcat:Dataset ; rdfs:label "Customer Master Dataset" . + + +# ============================================================================== +# EXAMPLE 7: SUPPORT PROMISE (v9.0) +# ============================================================================== +# +# Demonstrates structured support channel commitments including +# Slack, ticketing, and documentation with response time targets. +# +# ============================================================================== + +ex:supportContract a dprod:DataContract ; + rdfs:label "Contract with Support Channels" ; + odrl:assigner ex:DataPlatformTeam ; + odrl:assignee ex:BusinessIntelligenceTeam ; + odrl:target ex:salesMetricsDataset ; + dprod:contractStatus dprod:ContractStatusActive ; + + dprod:providerPromise [ + a dprod:ProviderSupportPromise ; + rdfs:label "Technical Support Commitment" ; + dct:description "Provider offers multi-channel support with defined response times for questions, issues, and self-service documentation." ; + odrl:action dprod:provideSupport ; + dprod:hasSupportChannel [ + a dprod:SupportChannel ; + rdfs:label "Slack Support" ; + dprod:channelType dprod:SlackSupport ; + dprod:channelUrl "https://company.slack.com/channels/data-platform-support"^^xsd:anyURI ; + dprod:supportScope dprod:InteractiveSupport ; + dprod:responseTimeTarget [ + a time:Duration ; + time:hours 4 + ] + ] , + [ + a dprod:SupportChannel ; + rdfs:label "JIRA Ticket System" ; + dprod:channelType dprod:TicketSupport ; + dprod:channelUrl "https://jira.company.com/servicedesk/data-platform"^^xsd:anyURI ; + dprod:supportScope dprod:IssueResolution ; + dprod:responseTimeTarget [ + a time:Duration ; + time:hours 24 + ] + ] , + [ + a dprod:SupportChannel ; + rdfs:label "Self-Service Documentation" ; + dprod:channelType dprod:DocumentationSupport ; + dprod:channelUrl "https://wiki.company.com/data-platform/sales-metrics"^^xsd:anyURI ; + dprod:supportScope dprod:SelfService + ] + ] . + +ex:DataPlatformTeam a odrl:Party ; rdfs:label "Data Platform Team" . +ex:BusinessIntelligenceTeam a odrl:Party ; rdfs:label "Business Intelligence Team" . +ex:salesMetricsDataset a dcat:Dataset ; rdfs:label "Sales Metrics Dataset" . + + +# ============================================================================== +# EXAMPLE 8: MARKETPLACE OFFER WITH PRICING (v9.0) +# ============================================================================== +# +# Shows how to attach pricing to data offers for marketplace scenarios. +# Uses schema:PriceSpecification for maximum compatibility. +# +# ============================================================================== + +ex:marketplaceOffer a dprod:DataOffer ; + rdfs:label "Weather Data Marketplace Offer" ; + dct:description "Commercial weather data offering with per-GB and subscription pricing options." ; + odrl:assigner ex:WeatherDataProvider ; + odrl:target ex:historicalWeatherDataset ; + dprod:contractStatus dprod:ContractStatusPending ; + + # Usage-based pricing + dprod:hasPricing [ + a schema:UnitPriceSpecification ; + rdfs:label "Pay-per-use pricing" ; + schema:price 0.05 ; + schema:priceCurrency "USD" ; + schema:unitText "per GB" ; + schema:referenceQuantity [ + a schema:QuantitativeValue ; + schema:value 1 ; + schema:unitCode "E34" # GB in UN/CEFACT + ] + ] ; + + dprod:providerPromise [ + a dprod:ProviderTimelinessPromise ; + rdfs:label "Hourly Weather Updates" ; + dct:description "Weather data refreshed every hour with latest observations." ; + odrl:action dprod:deliverOnSchedule ; + dprod:hasSchedule [ + a dprod:ICalSchedule ; + dprod:icalRule "FREQ=HOURLY;BYMINUTE=0" + ] + ] , + [ + a dprod:ProviderServiceLevelPromise ; + rdfs:label "API Availability" ; + odrl:action dprod:meetServiceLevel ; + dprod:hasServiceLevelTarget [ + a dprod:ServiceLevelTarget ; + dprod:slaMetric dprod:Availability ; + dprod:targetValue 99.5 ; + dprod:unit "percentage" + ] + ] . + +# Alternative subscription pricing example +ex:subscriptionOffer a dprod:DataOffer ; + rdfs:label "Weather Data Subscription" ; + odrl:assigner ex:WeatherDataProvider ; + odrl:target ex:historicalWeatherDataset ; + dprod:contractStatus dprod:ContractStatusPending ; + + dprod:hasPricing [ + a schema:PriceSpecification ; + rdfs:label "Monthly subscription" ; + schema:price 500 ; + schema:priceCurrency "USD" ; + schema:billingDuration "P1M"^^xsd:duration ; + dct:description "Monthly subscription for unlimited access to historical weather data" + ] . + +ex:WeatherDataProvider a odrl:Party ; rdfs:label "Weather Data Provider Inc." . +ex:historicalWeatherDataset a dcat:Dataset ; rdfs:label "Historical Weather Dataset" . + + +# ============================================================================== +# ACTION REFERENCE +# ============================================================================== +# +# Provider Promise Actions (use in dprod:ProviderPromise): +# dprod:deliverOnSchedule - Deliver per agreed schedule +# dprod:maintainSchema - Maintain schema conformance +# dprod:maintainQuality - Maintain data quality standards +# dprod:notifyChange - Notify of breaking changes +# dprod:notifyTermination - Provide termination notice +# dprod:provideSupport - Provide technical support +# +# Consumer Promise Actions (use in dprod:ConsumerPromise): +# +# Obligation actions: +# dprod:complyWithTerms - Comply with usage terms +# dprod:deleteOnExpiry - Delete data when contract expires +# dprod:reportUsage - Report usage metrics +# dprod:provideAttribution - Attribute data source +# dprod:restrictPurpose - Restrict to declared purpose (e.g., no redistribution) +# +# Data access actions (what consumer promises to do): +# dprod:query - Query the data service +# dprod:download - Download data locally +# dprod:stream - Receive real-time feeds +# dprod:access - General data access +# +# Transformation actions: +# dprod:deriveInsights - Create analytics/insights +# dprod:aggregate - Combine with other data +# dprod:anonymize - Remove PII before use +# dprod:enrich - Add value/annotations +# +# Distribution actions: +# dprod:shareInternally - Share within organization +# dprod:republish - Publish derived datasets +# +# ============================================================================== diff --git a/dprod-contracts/dprod-contracts-shapes.ttl b/dprod-contracts/dprod-contracts-shapes.ttl new file mode 100644 index 0000000..d973a85 --- /dev/null +++ b/dprod-contracts/dprod-contracts-shapes.ttl @@ -0,0 +1,560 @@ +@prefix dprod: . +@prefix dcat: . +@prefix dct: . +@prefix odrl: . +@prefix time: . +@prefix sh: . +@prefix xsd: . +@prefix schema: . +@prefix skos: . +@prefix rdfs: . +@prefix prov: . + +################################################################ +# SHACL Shapes for DPROD Data Contract Ontology +################################################################ +# Validation rules that complement the class definitions in drrod.ttl +# These shapes replace OWL restrictions for better platform compatibility +################################################################ + +# Shape for DataOffer +dprod:DataOfferShape + a sh:NodeShape ; + sh:targetClass dprod:DataOffer ; + sh:name "Data Offer Shape" ; + sh:description "Validation rules for data offers (provider's standing offers)" ; + + # Must have at least one asset target + sh:property [ + sh:path odrl:target ; + sh:minCount 1 ; + sh:class dcat:Resource ; + sh:name "offer target" ; + sh:description "An offer must govern at least one DCAT resource" ; + ] ; + + # Must have an assigner (provider) + sh:property [ + sh:path odrl:assigner ; + sh:minCount 1 ; + sh:name "offer assigner" ; + sh:description "An offer must specify the provider (assigner)" ; + ] ; +. + +# Shape for DataContract +dprod:DataContractShape + a sh:NodeShape ; + sh:targetClass dprod:DataContract ; + sh:name "Data Contract Shape" ; + sh:description "Validation rules for data contracts (bilateral agreements)" ; + + # Must have at least one asset target + sh:property [ + sh:path odrl:target ; + sh:minCount 1 ; + sh:class dcat:Resource ; + sh:name "contract target" ; + sh:description "A contract must govern at least one DCAT resource" ; + ] ; + + # Must have both assigner and assignee + sh:property [ + sh:path odrl:assigner ; + sh:minCount 1 ; + sh:name "contract assigner" ; + sh:description "A contract must specify the provider (assigner)" ; + ] ; + + sh:property [ + sh:path odrl:assignee ; + sh:minCount 1 ; + sh:name "contract assignee" ; + sh:description "A contract must specify the consumer (assignee)" ; + ] ; +. + + +# Shape for Promise (base) +dprod:PromiseShape + a sh:NodeShape ; + sh:targetClass dprod:Promise ; + sh:name "Promise Shape" ; + sh:description "Base validation for all promise types" ; + + # Must have an action specified + sh:property [ + sh:path odrl:action ; + sh:minCount 1 ; + sh:name "promise action" ; + sh:description "A promise must specify its action type" ; + ] ; + + # Must NOT be a Duty, Permission, or Prohibition (disjoint) + sh:not [ + sh:class odrl:Duty ; + ] ; + sh:not [ + sh:class odrl:Permission ; + ] ; + sh:not [ + sh:class odrl:Prohibition ; + ] ; +. + +# Shape for ProviderPromise +dprod:ProviderPromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ProviderPromise ; + sh:name "Provider Promise Shape" ; + sh:description "Validation for provider commitments" ; + + # Inherits base Promise constraints + sh:node dprod:PromiseShape ; + + # Must have a provider obligation action + sh:property [ + sh:path odrl:action ; + sh:minCount 1 ; + sh:in ( + dprod:deliverOnSchedule + dprod:maintainSchema + dprod:maintainQuality + dprod:meetServiceLevel + dprod:notifyChange + dprod:notifyTermination + dprod:provideSupport + ) ; + sh:name "provider action" ; + sh:description "Provider promises must use a provider obligation action (deliverOnSchedule, maintainSchema, maintainQuality, meetServiceLevel, notifyChange, notifyTermination, or provideSupport)" ; + ] ; +. + +# Shape for ConsumerPromise +dprod:ConsumerPromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ConsumerPromise ; + sh:name "Consumer Promise Shape" ; + sh:description "Validation for consumer commitments" ; + + # Inherits base Promise constraints + sh:node dprod:PromiseShape ; + + # Must have a consumer obligation action + sh:property [ + sh:path odrl:action ; + sh:minCount 1 ; + sh:in ( + dprod:complyWithTerms + dprod:deleteOnExpiry + dprod:reportUsage + dprod:provideAttribution + dprod:restrictPurpose + ) ; + sh:name "consumer action" ; + sh:description "Consumer promises must use a consumer obligation action (complyWithTerms, deleteOnExpiry, reportUsage, provideAttribution, or restrictPurpose)" ; + ] ; +. + +# Shape for ProviderTimelinessPromise +dprod:ProviderTimelinessPromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ProviderTimelinessPromise ; + sh:name "Provider Timeliness Promise Shape" ; + sh:description "Validation for time-based delivery commitments" ; + + # Inherits ProviderPromise constraints + sh:node dprod:ProviderPromiseShape ; + + # Must have deliverOnSchedule action + sh:property [ + sh:path odrl:action ; + sh:hasValue dprod:deliverOnSchedule ; + sh:minCount 1 ; + sh:name "timeliness action" ; + sh:description "Timeliness promises must use the 'deliverOnSchedule' action" ; + ] ; + + # Should have a schedule + sh:property [ + sh:path dprod:hasSchedule ; + sh:minCount 1 ; + sh:node dprod:ScheduleShape ; + sh:name "delivery schedule" ; + sh:description "Timeliness promises should specify a delivery schedule" ; + sh:severity sh:Warning ; + ] ; +. + +# Shape for ProviderSchemaPromise +dprod:ProviderSchemaPromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ProviderSchemaPromise ; + sh:name "Provider Schema Promise Shape" ; + sh:description "Validation for provider schema conformance commitments" ; + + # Inherits ProviderPromise constraints + sh:node dprod:ProviderPromiseShape ; + + # Must have maintainSchema action + sh:property [ + sh:path odrl:action ; + sh:hasValue dprod:maintainSchema ; + sh:minCount 1 ; + sh:name "schema action" ; + sh:description "Schema promises must use the 'maintainSchema' action" ; + ] ; + + # Should reference a schema + sh:property [ + sh:path dprod:requiresConformanceTo ; + sh:minCount 1 ; + sh:class dct:Standard ; + sh:name "schema reference" ; + sh:description "Schema promise should reference at least one schema/standard (SHACL shape, OWL ontology, or industry standard)" ; + sh:severity sh:Warning ; + ] ; +. + +# Shape for ProviderChangeNotificationPromise +dprod:ProviderChangeNotificationPromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ProviderChangeNotificationPromise ; + sh:name "Provider Change Notification Promise Shape" ; + sh:description "Validation for change/termination notification commitments" ; + + # Inherits ProviderPromise constraints + sh:node dprod:ProviderPromiseShape ; + + # Must have notifyChange action + sh:property [ + sh:path odrl:action ; + sh:hasValue dprod:notifyChange ; + sh:minCount 1 ; + sh:name "change notification action" ; + sh:description "Change notification promises must use the 'notifyChange' action" ; + ] ; +. + +# Shape for ProviderTerminationNoticePromise +dprod:ProviderTerminationNoticePromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ProviderTerminationNoticePromise ; + sh:name "Provider Termination Notice Promise Shape" ; + sh:description "Validation for advance termination/change notice commitments" ; + + # Inherits ProviderPromise constraints (not ChangeNotification, to allow different action) + sh:node dprod:ProviderPromiseShape ; + + # Must use the notifyTermination action + sh:property [ + sh:path odrl:action ; + sh:hasValue dprod:notifyTermination ; + sh:minCount 1 ; + sh:name "termination notice action" ; + sh:description "Termination notice promises must use the 'notifyTermination' action" ; + ] ; + + # Must state the notice period + sh:property [ + sh:path dprod:noticePeriod ; + sh:minCount 1 ; + sh:class time:Interval ; + sh:name "notice period" ; + sh:description "Specify the lead time interval consumers receive before termination or breaking changes" ; + ] ; +. + +# Shape for Schedule (union class validation) +dprod:ScheduleShape + a sh:NodeShape ; + sh:targetClass dprod:Schedule ; + sh:name "Schedule Shape" ; + sh:description "Validates that schedules are either schema:Schedule or iCal format" ; + + # Must be one of the two types + sh:or ( + [ sh:class schema:Schedule ] + [ sh:class dprod:ICalSchedule ] + ) ; +. + +# Shape for ICalSchedule +dprod:ICalScheduleShape + a sh:NodeShape ; + sh:targetClass dprod:ICalSchedule ; + sh:name "iCal Schedule Shape" ; + sh:description "Validates iCalendar RRULE schedules" ; + + # Must have exactly one icalRule + sh:property [ + sh:path dprod:icalRule ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:datatype xsd:string ; + sh:name "iCal rule" ; + sh:description "Must have exactly one RRULE string" ; + ] ; + + # Rule should follow iCal format (basic pattern check) + sh:property [ + sh:path dprod:icalRule ; + sh:pattern "^FREQ=(SECONDLY|MINUTELY|HOURLY|DAILY|WEEKLY|MONTHLY|YEARLY)" ; + sh:flags "i" ; + sh:name "iCal rule format" ; + sh:description "RRULE should start with FREQ=" ; + sh:severity sh:Warning ; + ] ; +. + +# Shape for hasEffectivePeriod time intervals +dprod:EffectivePeriodShape + a sh:NodeShape ; + sh:targetObjectsOf dprod:hasEffectivePeriod ; + sh:name "Effective Period Shape" ; + sh:description "Validates temporal intervals used for effective periods" ; + + # Must be a time:Interval + sh:class time:Interval ; + + # Should have a beginning + sh:property [ + sh:path time:hasBeginning ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:name "period start" ; + sh:description "Effective period should specify a beginning" ; + sh:severity sh:Warning ; + ] ; + + # May have an end + sh:property [ + sh:path time:hasEnd ; + sh:maxCount 1 ; + sh:name "period end" ; + ] ; +. + +# Shape for noticePeriod time intervals +dprod:NoticePeriodShape + a sh:NodeShape ; + sh:targetObjectsOf dprod:noticePeriod ; + sh:name "Notice Period Shape" ; + sh:description "Validates notice period intervals for termination/change commitments" ; + + # Must be a time:Interval + sh:class time:Interval ; + + # Should specify beginning and end boundaries + sh:property [ + sh:path time:hasBeginning ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:name "notice window start" ; + sh:severity sh:Warning ; + ] ; + + sh:property [ + sh:path time:hasEnd ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:name "notice window end" ; + sh:severity sh:Warning ; + ] ; +. + +# Shape for contract status values +dprod:ContractStatusConceptShape + a sh:NodeShape ; + sh:targetObjectsOf dprod:contractStatus ; + sh:name "Contract Status Concept Shape" ; + sh:description "Ensures contract status is from the correct scheme and class" ; + + # Must be a dprod:ContractStatus (which is a subclass of skos:Concept) + sh:class dprod:ContractStatus ; + + # Must be in the dprod:ContractStatusScheme scheme + sh:property [ + sh:path skos:inScheme ; + sh:hasValue dprod:ContractStatusScheme ; + sh:minCount 1 ; + ] ; +. + +# Shape for DataProduct linkage +dprod:DataProductShape + a sh:NodeShape ; + sh:targetClass dprod:DataProduct ; + sh:name "Data Product Shape" ; + sh:description "Validation for data product contract relationships" ; + + # May have contracts + sh:property [ + sh:path dprod:dataContract ; + sh:class dprod:DataContract ; + sh:name "data contract" ; + ] ; + + # May link to offers via odrl:hasPolicy + sh:property [ + sh:path odrl:hasPolicy ; + sh:class dprod:DataOffer ; + sh:name "data offer" ; + sh:description "Use odrl:hasPolicy to relate a product to published offers" ; + ] ; +. + +################################################################ +# v9.0 SHACL Shapes - Service Level and Support Promises +################################################################ + +# Shape for ProviderServiceLevelPromise +dprod:ProviderServiceLevelPromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ProviderServiceLevelPromise ; + sh:name "Provider Service Level Promise Shape" ; + sh:description "Validation for quantitative service level commitments" ; + + # Inherits ProviderPromise constraints + sh:node dprod:ProviderPromiseShape ; + + # Must have meetServiceLevel action + sh:property [ + sh:path odrl:action ; + sh:hasValue dprod:meetServiceLevel ; + sh:minCount 1 ; + sh:name "service level action" ; + sh:description "Service level promises must use the 'meetServiceLevel' action" ; + ] ; + + # Should have at least one service level target + sh:property [ + sh:path dprod:hasServiceLevelTarget ; + sh:minCount 1 ; + sh:node dprod:ServiceLevelTargetShape ; + sh:name "service level target" ; + sh:description "Service level promises should specify at least one quantitative target" ; + sh:severity sh:Warning ; + ] ; +. + +# Shape for ServiceLevelTarget +dprod:ServiceLevelTargetShape + a sh:NodeShape ; + sh:targetClass dprod:ServiceLevelTarget ; + sh:name "Service Level Target Shape" ; + sh:description "Validation for quantitative SLA targets" ; + + # Must have exactly one SLA metric + sh:property [ + sh:path dprod:slaMetric ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:class dprod:SLAMetric ; + sh:name "SLA metric" ; + sh:description "Must specify the type of metric being measured" ; + ] ; + + # Must have exactly one target value + sh:property [ + sh:path dprod:targetValue ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:datatype xsd:decimal ; + sh:name "target value" ; + sh:description "Must specify the numeric target value" ; + ] ; + + # Must have exactly one unit + sh:property [ + sh:path dprod:unit ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:datatype xsd:string ; + sh:name "unit" ; + sh:description "Must specify the unit of measurement" ; + ] ; + + # May have a measurement period + sh:property [ + sh:path dprod:measurementPeriod ; + sh:maxCount 1 ; + sh:class time:TemporalEntity ; + sh:name "measurement period" ; + sh:description "Time window over which the metric is measured" ; + ] ; +. + +# Shape for ProviderSupportPromise +dprod:ProviderSupportPromiseShape + a sh:NodeShape ; + sh:targetClass dprod:ProviderSupportPromise ; + sh:name "Provider Support Promise Shape" ; + sh:description "Validation for technical support commitments" ; + + # Inherits ProviderPromise constraints + sh:node dprod:ProviderPromiseShape ; + + # Must have provideSupport action + sh:property [ + sh:path odrl:action ; + sh:hasValue dprod:provideSupport ; + sh:minCount 1 ; + sh:name "support action" ; + sh:description "Support promises must use the 'provideSupport' action" ; + ] ; + + # Should have at least one support channel + sh:property [ + sh:path dprod:hasSupportChannel ; + sh:minCount 1 ; + sh:node dprod:SupportChannelShape ; + sh:name "support channel" ; + sh:description "Support promises should specify at least one support channel" ; + sh:severity sh:Warning ; + ] ; +. + +# Shape for SupportChannel +dprod:SupportChannelShape + a sh:NodeShape ; + sh:targetClass dprod:SupportChannel ; + sh:name "Support Channel Shape" ; + sh:description "Validation for support channel specifications" ; + + # Must have exactly one channel type + sh:property [ + sh:path dprod:channelType ; + sh:minCount 1 ; + sh:maxCount 1 ; + sh:class dprod:SupportChannelType ; + sh:name "channel type" ; + sh:description "Must specify the type of support channel" ; + ] ; + + # May have a channel URL + sh:property [ + sh:path dprod:channelUrl ; + sh:maxCount 1 ; + sh:datatype xsd:anyURI ; + sh:name "channel URL" ; + sh:description "URL or address for accessing the support channel" ; + ] ; + + # May have a response time target + sh:property [ + sh:path dprod:responseTimeTarget ; + sh:maxCount 1 ; + sh:class time:Duration ; + sh:name "response time target" ; + sh:description "Target response time for this channel" ; + ] ; + + # May have a support scope + sh:property [ + sh:path dprod:supportScope ; + sh:class dprod:SupportScope ; + sh:name "support scope" ; + sh:description "What this channel covers" ; + ] ; +. diff --git a/dprod-contracts/dprod-contracts.ttl b/dprod-contracts/dprod-contracts.ttl new file mode 100644 index 0000000..8c25ed8 --- /dev/null +++ b/dprod-contracts/dprod-contracts.ttl @@ -0,0 +1,1132 @@ +@prefix dprod: . +@prefix dcat: . +@prefix dct: . +@prefix odrl: . +@prefix prov: . +@prefix org: . +@prefix skos: . +@prefix rdfs: . +@prefix owl: . +@prefix xsd: . +@prefix time: . +@prefix adms: . +@prefix schema: . + + +# ============================================================================== +# ONTOLOGY DECLARATION +# ============================================================================== + + + a owl:Ontology ; + rdfs:label "DPROD Data Contracts Ontology"@en ; + dct:title "DPROD Data Contracts Ontology"@en ; + dct:description "A semantic web ontology for formalizing bilateral data agreements between providers and consumers using W3C standards (RDF, OWL, SHACL, ODRL, DCAT)."@en ; + dct:creator "EKGF DPROD Working Group" ; + dct:created "2025-10-30"^^xsd:date ; + dct:modified "2025-01-08"^^xsd:date ; + owl:versionInfo "9.0.0" ; + owl:versionIRI ; + owl:imports , + , + , + , + ; + rdfs:seeAlso . + + +# ============================================================================== +# CORE CLASSES - Contract & Offer Classes +# ============================================================================== + +dprod:DataContract + a owl:Class ; + rdfs:label "Data Contract"@en ; + skos:definition "Bilateral agreement establishing binding obligations between data provider (assigner) and consumer (assignee), formed when a consumer accepts a DataOffer."@en ; + rdfs:subClassOf odrl:Agreement ; + rdfs:isDefinedBy ; + skos:note "Extends odrl:Agreement to represent accepted terms. Both parties are bound by their respective promises. Use odrl:assigner for provider and odrl:assignee for consumer."@en ; + skos:example "An executed agreement for daily customer data updates, with provider committed to 6am delivery and consumer bound by usage restrictions"@en . + +dprod:DataOffer + a owl:Class ; + rdfs:label "Data Offer"@en ; + skos:definition "Provider's standing offer containing proposed terms, promises, and constraints available for consumer acceptance. Becomes binding upon acceptance to form a DataContract."@en ; + rdfs:subClassOf odrl:Offer ; + rdfs:isDefinedBy ; + skos:note "Represents the provider's proposed terms, published for discovery. Not binding until accepted. Use odrl:assigner to specify the offering party."@en ; + skos:example "A published offer for daily customer data updates via REST API with 6am refresh schedule, including timeliness and schema promises"@en . + + +# ============================================================================== +# CORE CLASSES - Promise Classes +# ============================================================================== + +dprod:Promise + a owl:Class ; + rdfs:label "Promise"@en ; + skos:definition "Commitment from one party to another in a data contract"@en ; + rdfs:subClassOf odrl:Rule ; + owl:disjointWith odrl:Duty, odrl:Permission, odrl:Prohibition ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note """Base class for all commitments - service levels, quality guarantees, usage compliance, etc. + Use odrl:action to specify the type of commitment using DPROD actions. + Provider actions: dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport. + Consumer actions: dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, dprod:provideAttribution, dprod:restrictPurpose. + """@en . + +dprod:ProviderPromise + a owl:Class ; + rdfs:label "Provider Promise"@en ; + skos:definition "Promise made by data providers about service delivery or data quality"@en ; + rdfs:subClassOf dprod:Promise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Use for commitments about data provision, service levels, quality guarantees, and operational responsibilities. Use provider obligation actions: dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport."@en . + +dprod:ConsumerPromise + a owl:Class ; + rdfs:label "Consumer Promise"@en ; + skos:definition "Promise made by data consumer to abide by usage terms, compliance requirements, and license agreements"@en ; + rdfs:subClassOf dprod:Promise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Use for commitments about usage compliance, attribution, redistribution limits, and confidentiality. Use consumer obligation actions: dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, dprod:provideAttribution, dprod:restrictPurpose."@en . + +dprod:ProviderTimelinessPromise + a owl:Class ; + rdfs:label "Provider Timeliness Promise"@en ; + skos:definition "Timeliness promise made by data providers about time-based delivery commitments"@en ; + rdfs:subClassOf dprod:ProviderPromise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Specialized promise for time-based service delivery commitments. Use dprod:deliverOnSchedule action. This will often refer to a recurring schedule via dprod:hasSchedule."@en . + +dprod:ProviderSchemaPromise + a owl:Class ; + rdfs:label "Provider Schema Promise"@en ; + skos:definition "Promise made by data providers about schema conformance for a specific dataset or resource"@en ; + rdfs:subClassOf dprod:ProviderPromise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Use dprod:maintainSchema action. Use odrl:target to identify the specific dataset/distribution and dprod:requiresConformanceTo to reference the schema (SHACL shape, OWL ontology, etc.) it must conform to. This creates a contractual binding between a resource and a schema specification. The targeted resource should declare dct:conformsTo with the same schema. Typically specifies a constrained view or subset of the full dataset schema. The promised schema defines what consumers can rely upon, which may be more stable than the source schema."@en ; + skos:example "A promise with odrl:target pointing to :customerDataset and dprod:requiresConformanceTo pointing to CustomerDataShape.ttl commits the provider to deliver that specific dataset conforming to that shape."@en . + +dprod:ProviderChangeNotificationPromise + a owl:Class ; + rdfs:label "Provider Change Notification Promise"@en ; + skos:definition "Change notification promise made by data providers about service delivery changes"@en ; + rdfs:subClassOf dprod:ProviderPromise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Use dprod:notifyChange action. Use for commitments that require notifying consumers about impending changes. Subclasses capture specific notice expectations such as termination lead time."@en . + +dprod:ProviderTerminationNoticePromise + a owl:Class ; + rdfs:label "Provider Termination Notice Promise"@en ; + skos:definition "Promise made by data providers to give advance notice before terminating a contract or introducing breaking changes."@en ; + rdfs:subClassOf dprod:ProviderChangeNotificationPromise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Use dprod:notifyTermination action. Capture required notice periods using dprod:noticePeriod. This distinguishes advance termination notifications from other change alerts."@en . + +dprod:ProviderServiceLevelPromise + a owl:Class ; + rdfs:label "Provider Service Level Promise"@en ; + skos:definition "Promise with quantitative service level targets such as availability, latency, and throughput."@en ; + rdfs:subClassOf dprod:ProviderPromise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Use dprod:meetServiceLevel action. Attach quantitative targets via dprod:hasServiceLevelTarget. Each target specifies a metric, value, unit, and optional measurement period."@en ; + skos:example "A promise guaranteeing 99.9% monthly availability and p95 response time under 500ms."@en . + +dprod:ProviderSupportPromise + a owl:Class ; + rdfs:label "Provider Support Promise"@en ; + skos:definition "Promise about technical support availability including channels, scope, and response times."@en ; + rdfs:subClassOf dprod:ProviderPromise ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Use dprod:provideSupport action. Specify support channels via dprod:hasSupportChannel with channel type, URL, scope, and response time targets."@en ; + skos:example "A promise providing Slack support with 4-hour response time and ticket system for issue resolution."@en . + + +# ============================================================================== +# CORE CLASSES - SLA Target and Support Channel Classes +# ============================================================================== + +dprod:ServiceLevelTarget + a owl:Class ; + rdfs:label "Service Level Target"@en ; + skos:definition "A quantitative target for a specific service level metric."@en ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Captures metric type (dprod:slaMetric), numeric target (dprod:targetValue), unit of measurement (dprod:unit), and optional measurement period (dprod:measurementPeriod)."@en . + +dprod:SupportChannel + a owl:Class ; + rdfs:label "Support Channel"@en ; + skos:definition "A communication channel for obtaining technical support."@en ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Specify channel type, URL, support scope, and response time target."@en . + + +# ============================================================================== +# CORE CLASSES - Schedule Classes +# ============================================================================== + +dprod:Schedule + a owl:Class ; + rdfs:label "Schedule"@en ; + skos:definition "Flexible schedule specification supporting multiple temporal formats"@en ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "Instances should be either schema:Schedule or dprod:ICalSchedule. Validation enforced by SHACL. For validity periods, use dprod:hasEffectivePeriod with time:Interval."@en . + +dprod:ICalSchedule + a owl:Class ; + rdfs:label "iCal Schedule"@en ; + skos:definition "Schedule expressed using iCalendar RRULE format"@en ; + rdfs:isDefinedBy ; + skos:inScheme ; + skos:note "For complex recurring schedules using standard iCal RRULE syntax. Validation enforced by SHACL: must have exactly one dprod:icalRule."@en . + + +# ============================================================================== +# ODRL ACTIONS - Data Access +# ============================================================================== + +dprod:DataAccessAction + a skos:Concept ; + rdfs:label "Data Access Action"@en ; + skos:prefLabel "Data Access Action"@en ; + skos:definition "Actions that allow consumers to access and retrieve data from the provider."@en ; + skos:inScheme ; + skos:topConceptOf ; + rdfs:isDefinedBy ; + skos:narrower dprod:query, dprod:download, dprod:stream, dprod:access . + +dprod:query + a odrl:Action, skos:Concept ; + rdfs:label "Query"@en ; + skos:prefLabel "query"@en ; + skos:definition "Execute queries against a data service to retrieve specific data subsets."@en ; + odrl:includedIn odrl:read ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:download + a odrl:Action, skos:Concept ; + rdfs:label "Download"@en ; + skos:prefLabel "download"@en ; + skos:definition "Download data assets for local storage and offline use."@en ; + odrl:includedIn odrl:reproduce ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:stream + a odrl:Action, skos:Concept ; + rdfs:label "Stream"@en ; + skos:prefLabel "stream"@en ; + skos:definition "Receive real-time data feeds or continuous data streams."@en ; + odrl:includedIn odrl:stream ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:access + a odrl:Action, skos:Concept ; + rdfs:label "Access"@en ; + skos:prefLabel "access"@en ; + skos:definition "General access to a data asset without specifying the access method."@en ; + odrl:includedIn odrl:use ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy ; + skos:inScheme . + + +# ============================================================================== +# ODRL ACTIONS - Data Transformation +# ============================================================================== + +dprod:DataTransformationAction + a skos:Concept ; + rdfs:label "Data Transformation Action"@en ; + skos:prefLabel "Data Transformation Action"@en ; + skos:definition "Actions that allow consumers to transform, derive, or modify data."@en ; + skos:inScheme ; + skos:topConceptOf ; + rdfs:isDefinedBy ; + skos:narrower dprod:deriveInsights, dprod:aggregate, dprod:anonymize, dprod:enrich . + +dprod:deriveInsights + a odrl:Action, skos:Concept ; + rdfs:label "Derive Insights"@en ; + skos:prefLabel "derive insights"@en ; + skos:definition "Create analytics, reports, or insights derived from the data asset."@en ; + odrl:includedIn odrl:derive ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:aggregate + a odrl:Action, skos:Concept ; + rdfs:label "Aggregate"@en ; + skos:prefLabel "aggregate"@en ; + skos:definition "Combine data with other data sources to create aggregated datasets."@en ; + odrl:includedIn odrl:aggregate ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:anonymize + a odrl:Action, skos:Concept ; + rdfs:label "Anonymize"@en ; + skos:prefLabel "anonymize"@en ; + skos:definition "Remove personally identifiable information before further use or distribution."@en ; + odrl:includedIn odrl:anonymize ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:enrich + a odrl:Action, skos:Concept ; + rdfs:label "Enrich"@en ; + skos:prefLabel "enrich"@en ; + skos:definition "Add value, annotations, or additional attributes to data assets."@en ; + odrl:includedIn odrl:modify ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + + +# ============================================================================== +# ODRL ACTIONS - Distribution +# ============================================================================== + +dprod:DistributionAction + a skos:Concept ; + rdfs:label "Distribution Action"@en ; + skos:prefLabel "Distribution Action"@en ; + skos:definition "Actions that allow consumers to distribute or share data with others."@en ; + skos:inScheme ; + skos:topConceptOf ; + rdfs:isDefinedBy ; + skos:narrower dprod:redistribute, dprod:republish, dprod:shareInternally . + +dprod:redistribute + a odrl:Action, skos:Concept ; + rdfs:label "Redistribute"@en ; + skos:prefLabel "redistribute"@en ; + skos:definition "Share data assets with third parties outside the organization."@en ; + odrl:includedIn odrl:distribute ; + skos:broader dprod:DistributionAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:republish + a odrl:Action, skos:Concept ; + rdfs:label "Republish"@en ; + skos:prefLabel "republish"@en ; + skos:definition "Publish derived datasets or data products based on the original data."@en ; + odrl:includedIn odrl:reproduce ; + skos:broader dprod:DistributionAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:shareInternally + a odrl:Action, skos:Concept ; + rdfs:label "Share Internally"@en ; + skos:prefLabel "share internally"@en ; + skos:definition "Share data assets within the organization or organizational unit."@en ; + odrl:includedIn odrl:distribute ; + skos:broader dprod:DistributionAction ; + rdfs:isDefinedBy ; + skos:inScheme . + + +# ============================================================================== +# ODRL ACTIONS - Provider Obligations +# ============================================================================== + +dprod:ProviderObligationAction + a skos:Concept ; + rdfs:label "Provider Obligation Action"@en ; + skos:prefLabel "Provider Obligation Action"@en ; + skos:definition "Actions representing obligations the provider commits to fulfill."@en ; + skos:inScheme ; + skos:topConceptOf ; + rdfs:isDefinedBy ; + skos:narrower dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, + dprod:meetServiceLevel, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport . + +dprod:deliverOnSchedule + a odrl:Action, skos:Concept ; + rdfs:label "Deliver on Schedule"@en ; + skos:prefLabel "deliver on schedule"@en ; + skos:definition "Deliver data according to the agreed schedule specified in the contract."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:maintainSchema + a odrl:Action, skos:Concept ; + rdfs:label "Maintain Schema"@en ; + skos:prefLabel "maintain schema"@en ; + skos:definition "Maintain schema conformance as specified in the contract."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:maintainQuality + a odrl:Action, skos:Concept ; + rdfs:label "Maintain Quality"@en ; + skos:prefLabel "maintain quality"@en ; + skos:definition "Maintain data quality standards as specified in the contract."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:meetServiceLevel + a odrl:Action, skos:Concept ; + rdfs:label "Meet Service Level"@en ; + skos:prefLabel "meet service level"@en ; + skos:definition "Meet the quantitative service level targets specified in the contract."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:notifyChange + a odrl:Action, skos:Concept ; + rdfs:label "Notify Change"@en ; + skos:prefLabel "notify change"@en ; + skos:definition "Notify consumers of breaking changes, schema updates, or service modifications."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:notifyTermination + a odrl:Action, skos:Concept ; + rdfs:label "Notify Termination"@en ; + skos:prefLabel "notify termination"@en ; + skos:definition "Provide advance notice before terminating the contract or discontinuing the service."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:provideSupport + a odrl:Action, skos:Concept ; + rdfs:label "Provide Support"@en ; + skos:prefLabel "provide support"@en ; + skos:definition "Provide technical support for data access and integration issues."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + + +# ============================================================================== +# ODRL ACTIONS - Consumer Obligations +# ============================================================================== + +dprod:ConsumerObligationAction + a skos:Concept ; + rdfs:label "Consumer Obligation Action"@en ; + skos:prefLabel "Consumer Obligation Action"@en ; + skos:definition "Actions representing obligations the consumer commits to fulfill."@en ; + skos:inScheme ; + skos:topConceptOf ; + rdfs:isDefinedBy ; + skos:narrower dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, + dprod:provideAttribution, dprod:restrictPurpose . + +dprod:complyWithTerms + a odrl:Action, skos:Concept ; + rdfs:label "Comply with Terms"@en ; + skos:prefLabel "comply with terms"@en ; + skos:definition "Accept and comply with all usage terms specified in the contract."@en ; + odrl:includedIn odrl:acceptTracking ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:deleteOnExpiry + a odrl:Action, skos:Concept ; + rdfs:label "Delete on Expiry"@en ; + skos:prefLabel "delete on expiry"@en ; + skos:definition "Delete all copies of the data when the contract expires or is terminated."@en ; + odrl:includedIn odrl:delete ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:reportUsage + a odrl:Action, skos:Concept ; + rdfs:label "Report Usage"@en ; + skos:prefLabel "report usage"@en ; + skos:definition "Report usage metrics and access patterns to the data provider."@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:provideAttribution + a odrl:Action, skos:Concept ; + rdfs:label "Provide Attribution"@en ; + skos:prefLabel "provide attribution"@en ; + skos:definition "Provide proper attribution to the data source in any derived works or publications."@en ; + odrl:includedIn odrl:attribute ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + +dprod:restrictPurpose + a odrl:Action, skos:Concept ; + rdfs:label "Restrict Purpose"@en ; + skos:prefLabel "restrict purpose"@en ; + skos:definition "Restrict data usage to the declared purpose specified in the contract."@en ; + odrl:includedIn odrl:use ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy ; + skos:inScheme . + + +# ============================================================================== +# PROPERTIES - Promise Linking +# ============================================================================== + +dprod:hasPromise + a owl:ObjectProperty ; + rdfs:label "has promise"@en ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range dprod:Promise ; + dct:description "Links a contract to any binding commitment (promise), whether undertaken by provider or consumer. Use specific subproperties (providerPromise, consumerPromise) when the commitment direction is known."@en ; + rdfs:isDefinedBy . + +dprod:providerPromise + a owl:ObjectProperty ; + rdfs:label "provider promise"@en ; + rdfs:subPropertyOf dprod:hasPromise ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range dprod:ProviderPromise ; + dct:description "Affirmative obligations undertaken by the data provider, including warranties about data quality, service level commitments (SLAs), delivery timeliness, schema stability, and change notification requirements. Represents what the provider commits to deliver or maintain."@en ; + rdfs:isDefinedBy . + +dprod:consumerPromise + a owl:ObjectProperty ; + rdfs:label "consumer promise"@en ; + rdfs:subPropertyOf dprod:hasPromise ; + rdfs:domain dprod:DataContract ; + rdfs:range dprod:ConsumerPromise ; + dct:description "Restrictive covenants and use obligations binding the consumer, including permitted/prohibited uses, compliance requirements, attribution obligations, redistribution limits, and confidentiality terms. Represents what the consumer agrees to do or refrain from doing."@en ; + rdfs:isDefinedBy . + + +# ============================================================================== +# PROPERTIES - Data Product Linking +# ============================================================================== + +dprod:dataContract + a owl:ObjectProperty ; + rdfs:label "data contract"@en ; + rdfs:domain dprod:DataProduct ; + rdfs:range dprod:DataContract ; + rdfs:subPropertyOf odrl:hasPolicy ; + dct:description "Contract(s) governing a data product's inputs, outputs, or access services."@en ; + rdfs:isDefinedBy . + +dprod:contractStatus + a owl:ObjectProperty, owl:FunctionalProperty ; + rdfs:label "contract status"@en ; + skos:definition "Current lifecycle status of a data contract or offer"@en ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range dprod:ContractStatus ; + rdfs:subPropertyOf adms:status ; + dct:description "Lifecycle status indicating whether the contract or offer is Pending, Active, Expired, or Cancelled. Values must be instances of dprod:ContractStatus from the dprod:ContractStatusScheme."@en ; + rdfs:isDefinedBy ; + skos:note "Functional property - each contract/offer has at most one status value at any given time."@en . + + +# ============================================================================== +# PROPERTIES - Contract Versioning & Provenance +# ============================================================================== + +dprod:supersedes + a owl:ObjectProperty ; + rdfs:label "supersedes"@en ; + skos:definition "This contract supersedes and replaces a previous contract"@en ; + rdfs:subPropertyOf prov:wasRevisionOf, dct:replaces ; + rdfs:domain dprod:DataContract ; + rdfs:range dprod:DataContract ; + dct:description "Links a contract to the previous version it supersedes. Use for contract renewals where the new contract completely replaces the old one. The superseded contract typically transitions to Expired or Cancelled status."@en ; + rdfs:isDefinedBy ; + skos:note "Enables version tracking: Contract v2.0 supersedes Contract v1.0. Useful for understanding contract evolution and maintaining audit trails."@en ; + skos:example """ + # Contract renewal: + :contract2025 a dprod:DataContract ; + dprod:supersedes :contract2024 ; + dcat:version "2.0" ; + rdfs:comment "Annual renewal with updated SLAs" . + + :contract2024 dprod:contractStatus dprod:ContractStatusExpired . + """@en . + +dprod:amends + a owl:ObjectProperty ; + rdfs:label "amends"@en ; + skos:definition "This contract amends or extends an existing active contract"@en ; + rdfs:subPropertyOf prov:wasRevisionOf ; + rdfs:domain dprod:DataContract ; + rdfs:range dprod:DataContract ; + dct:description "Links an amendment/addendum to the base contract it modifies. Use when both contracts remain active simultaneously - the amendment adds to or modifies specific terms without replacing the entire base contract."@en ; + rdfs:isDefinedBy ; + skos:note "Enables tracking of contract amendments and addendums. Multiple amendments can reference the same base contract. Both the base contract and amendments can be Active simultaneously."@en ; + skos:example """ + # Base contract with multiple amendments: + :baseContract a dprod:DataContract ; + dcat:version "1.0" ; + dprod:contractStatus dprod:ContractStatusActive . + + :amendment1 a dprod:DataContract ; + dprod:amends :baseContract ; + dcat:version "1.1-amendment" ; + rdfs:comment "Adds GDPR compliance requirements" ; + dprod:contractStatus dprod:ContractStatusActive . + + :amendment2 a dprod:DataContract ; + dprod:amends :baseContract ; + dcat:version "1.2-amendment" ; + rdfs:comment "Adds new dataset to scope" ; + dprod:contractStatus dprod:ContractStatusActive . + """@en . + + +# ============================================================================== +# PROPERTIES - Temporal Properties +# ============================================================================== + +dprod:hasEffectivePeriod + a owl:ObjectProperty ; + rdfs:label "has effective period"@en ; + skos:definition "Effective period (convenience property aligned with dcterms:temporal)"@en ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract dprod:Promise ) ] ; + rdfs:range time:Interval ; + rdfs:subPropertyOf dct:temporal ; + rdfs:isDefinedBy ; + skos:note "For structured time intervals only. Use time:hasBeginning and time:hasEnd on the Interval. For textual period expressions, use dcterms:temporal directly on the offer or contract."@en . + +dprod:noticePeriod + a owl:ObjectProperty ; + rdfs:label "notice period"@en ; + skos:definition "Advance notice interval that must elapse before a termination or breaking change takes effect."@en ; + rdfs:domain dprod:ProviderTerminationNoticePromise ; + rdfs:range time:Interval ; + rdfs:subPropertyOf dct:temporal ; + rdfs:isDefinedBy ; + skos:note "Describe lead time requirements by providing time:hasBeginning and time:hasEnd values on the interval (e.g., 90-day notice)."@en . + +dprod:hasSchedule + a owl:ObjectProperty ; + rdfs:label "has schedule"@en ; + skos:definition "Schedule specification for provider promises with flexible format support"@en ; + rdfs:domain dprod:ProviderTimelinessPromise ; + rdfs:range dprod:Schedule ; + rdfs:subPropertyOf dct:temporal ; + rdfs:isDefinedBy ; + skos:note "Accepts time:TemporalEntity, schema:Schedule, or dprod:ICalSchedule formats"@en . + +dprod:requiresConformanceTo + a owl:ObjectProperty ; + rdfs:label "requires conformance to"@en ; + skos:definition "Schema, model, or standard that the targeted resource must conform to"@en ; + rdfs:domain dprod:ProviderSchemaPromise ; + rdfs:range dct:Standard ; + dct:description "Specifies the schema/standard that the resource identified by odrl:target must conform to. Use alongside odrl:target to bind a specific dataset/distribution to a schema requirement. The targeted resource should declare dct:conformsTo with the same schema. Typically references SHACL shapes, OWL ontologies, or industry standards (e.g., FIBO, schema.org profiles)."@en ; + rdfs:isDefinedBy ; + skos:note "Works in conjunction with odrl:target. The promise targets a specific dataset (via odrl:target) and requires it to conform to a schema (via dprod:requiresConformanceTo). The referenced schema becomes a contractual commitment."@en ; + skos:example """ + # Promise binds specific dataset to schema: + :schemaPromise a dprod:ProviderSchemaPromise ; + odrl:action dprod:maintainSchema ; + odrl:target :customerDataset ; + dprod:requiresConformanceTo . + """@en . + + +# ============================================================================== +# PROPERTIES - Service Level Properties +# ============================================================================== + +dprod:hasServiceLevelTarget + a owl:ObjectProperty ; + rdfs:label "has service level target"@en ; + skos:definition "Links a service level promise to its quantitative targets"@en ; + rdfs:domain dprod:ProviderServiceLevelPromise ; + rdfs:range dprod:ServiceLevelTarget ; + rdfs:isDefinedBy . + +dprod:slaMetric + a owl:ObjectProperty ; + rdfs:label "SLA metric"@en ; + skos:definition "The type of service level metric being measured"@en ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range dprod:SLAMetric ; + rdfs:isDefinedBy . + +dprod:targetValue + a owl:DatatypeProperty ; + rdfs:label "target value"@en ; + skos:definition "The numeric target value for this metric"@en ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range xsd:decimal ; + rdfs:isDefinedBy . + +dprod:unit + a owl:DatatypeProperty ; + rdfs:label "unit"@en ; + skos:definition "Unit of measurement (percentage, milliseconds, requests/second, etc.)"@en ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range xsd:string ; + rdfs:isDefinedBy . + +dprod:measurementPeriod + a owl:ObjectProperty ; + rdfs:label "measurement period"@en ; + skos:definition "The time window over which the metric is measured"@en ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range time:TemporalEntity ; + rdfs:isDefinedBy . + + +# ============================================================================== +# PROPERTIES - Support Channel Properties +# ============================================================================== + +dprod:hasSupportChannel + a owl:ObjectProperty ; + rdfs:label "has support channel"@en ; + skos:definition "Links a support promise to available support channels"@en ; + rdfs:domain dprod:ProviderSupportPromise ; + rdfs:range dprod:SupportChannel ; + rdfs:isDefinedBy . + +dprod:channelType + a owl:ObjectProperty ; + rdfs:label "channel type"@en ; + skos:definition "The type of support channel (email, Slack, ticket system, etc.)"@en ; + rdfs:domain dprod:SupportChannel ; + rdfs:range dprod:SupportChannelType ; + rdfs:isDefinedBy . + +dprod:channelUrl + a owl:DatatypeProperty ; + rdfs:label "channel URL"@en ; + skos:definition "URL or address for accessing this support channel"@en ; + rdfs:domain dprod:SupportChannel ; + rdfs:range xsd:anyURI ; + rdfs:isDefinedBy . + +dprod:responseTimeTarget + a owl:ObjectProperty ; + rdfs:label "response time target"@en ; + skos:definition "Target response time for this support channel"@en ; + rdfs:domain dprod:SupportChannel ; + rdfs:range time:Duration ; + rdfs:isDefinedBy . + +dprod:supportScope + a owl:ObjectProperty ; + rdfs:label "support scope"@en ; + skos:definition "What this channel covers (issues, questions, announcements)"@en ; + rdfs:domain dprod:SupportChannel ; + rdfs:range dprod:SupportScope ; + rdfs:isDefinedBy . + + +# ============================================================================== +# PROPERTIES - Pricing +# ============================================================================== + +dprod:hasPricing + a owl:ObjectProperty ; + rdfs:label "has pricing"@en ; + skos:definition "Pricing terms for data access under this contract"@en ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range schema:PriceSpecification ; + rdfs:isDefinedBy ; + skos:note "Use schema:PriceSpecification subclasses for different pricing models (per-unit, subscription, tiered). Optional - typically only used for external marketplace scenarios."@en . + + +# ============================================================================== +# PROPERTIES - Schedule Properties +# ============================================================================== + +dprod:icalRule + a owl:DatatypeProperty ; + rdfs:label "iCal rule"@en ; + skos:definition "iCalendar RRULE specification for recurring schedules"@en ; + rdfs:domain dprod:ICalSchedule ; + rdfs:range xsd:string ; + rdfs:isDefinedBy ; + skos:note "Standard RFC 5545 RRULE format, e.g., 'FREQ=DAILY;BYHOUR=6;BYMINUTE=0'"@en . + + +# ============================================================================== +# CONTRACT STATUS VOCABULARY +# ============================================================================== + +dprod:ContractStatusScheme + a skos:ConceptScheme ; + rdfs:label "DPROD Contract Status"@en ; + skos:definition "Vocabulary for data contract and offer lifecycle status values"@en ; + skos:hasTopConcept + dprod:ContractStatusPending, + dprod:ContractStatusActive, + dprod:ContractStatusExpired, + dprod:ContractStatusCancelled ; + rdfs:isDefinedBy ; + skos:note "Status concepts apply to both DataOffer (Pending, Expired, Cancelled) and DataContract (Active, Expired, Cancelled)"@en . + +dprod:ContractStatus + a owl:Class ; + rdfs:label "Contract Status"@en ; + skos:definition "Status value for data contracts and offers"@en ; + rdfs:subClassOf skos:Concept ; + rdfs:isDefinedBy ; + skos:note "Subclass of skos:Concept providing specific typing for contract lifecycle status values"@en . + +dprod:ContractStatusPending + a dprod:ContractStatus ; + rdfs:label "Pending"@en ; + skos:prefLabel "Pending"@en ; + skos:definition "Offer is published and available for review, but not yet accepted by any consumer."@en ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; + rdfs:isDefinedBy ; + skos:note "Applies to DataOffer only. Provider commitments are proposed but not yet binding. Once accepted, status becomes Active."@en . + +dprod:ContractStatusActive + a dprod:ContractStatus ; + rdfs:label "Active"@en ; + skos:prefLabel "Active"@en ; + skos:definition "Data contract is in operation"@en ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; + rdfs:isDefinedBy ; + skos:note "Contract is in effect. Provider commitments are in operation."@en . + +dprod:ContractStatusExpired + a dprod:ContractStatus ; + rdfs:label "Expired"@en ; + skos:prefLabel "Expired"@en ; + skos:definition "Contract or offer has reached its natural end date as specified in the effective period."@en ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; + rdfs:isDefinedBy ; + skos:note "Contract reached its scheduled termination date. Provider commitments are no longer in effect. Distinct from cancellation (early termination)."@en . + +dprod:ContractStatusCancelled + a dprod:ContractStatus ; + rdfs:label "Cancelled"@en ; + skos:prefLabel "Cancelled"@en ; + skos:definition "Data contract has been cancelled before its planned retirement"@en ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; + rdfs:isDefinedBy ; + skos:note "Contract has been cancelled. Provider commitments are no longer valid."@en . + + +# ============================================================================== +# SLA METRIC VOCABULARY +# ============================================================================== + +dprod:SLAMetricScheme + a skos:ConceptScheme ; + rdfs:label "DPROD SLA Metrics"@en ; + skos:definition "Vocabulary for service level agreement metrics"@en ; + skos:hasTopConcept dprod:Availability, dprod:Latency, dprod:Throughput, + dprod:ErrorRate, dprod:ResponseTime ; + rdfs:isDefinedBy . + +dprod:SLAMetric + a owl:Class ; + rdfs:label "SLA Metric"@en ; + skos:definition "Type of service level metric"@en ; + rdfs:subClassOf skos:Concept ; + rdfs:isDefinedBy . + +dprod:Availability + a dprod:SLAMetric ; + rdfs:label "Availability"@en ; + skos:prefLabel "Availability"@en ; + skos:definition "Percentage of time the service is operational and accessible"@en ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; + rdfs:isDefinedBy . + +dprod:Latency + a dprod:SLAMetric ; + rdfs:label "Latency"@en ; + skos:prefLabel "Latency"@en ; + skos:definition "Time delay in data delivery or processing"@en ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; + rdfs:isDefinedBy . + +dprod:Throughput + a dprod:SLAMetric ; + rdfs:label "Throughput"@en ; + skos:prefLabel "Throughput"@en ; + skos:definition "Volume of data processed per unit time"@en ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; + rdfs:isDefinedBy . + +dprod:ErrorRate + a dprod:SLAMetric ; + rdfs:label "Error Rate"@en ; + skos:prefLabel "Error Rate"@en ; + skos:definition "Percentage of failed requests or invalid records"@en ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; + rdfs:isDefinedBy . + +dprod:ResponseTime + a dprod:SLAMetric ; + rdfs:label "Response Time"@en ; + skos:prefLabel "Response Time"@en ; + skos:definition "Time to respond to a request (may specify percentile: p50, p95, p99)"@en ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; + rdfs:isDefinedBy . + + +# ============================================================================== +# SUPPORT CHANNEL TYPE VOCABULARY +# ============================================================================== + +dprod:SupportChannelTypeScheme + a skos:ConceptScheme ; + rdfs:label "Support Channel Types"@en ; + skos:definition "Types of support channels available for data contracts"@en ; + skos:hasTopConcept dprod:EmailSupport, dprod:SlackSupport, dprod:TeamsSupport, + dprod:TicketSupport, dprod:DocumentationSupport ; + rdfs:isDefinedBy . + +dprod:SupportChannelType + a owl:Class ; + rdfs:label "Support Channel Type"@en ; + skos:definition "Type of support channel"@en ; + rdfs:subClassOf skos:Concept ; + rdfs:isDefinedBy . + +dprod:EmailSupport + a dprod:SupportChannelType ; + rdfs:label "Email"@en ; + skos:prefLabel "Email"@en ; + skos:definition "Support via email"@en ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; + rdfs:isDefinedBy . + +dprod:SlackSupport + a dprod:SupportChannelType ; + rdfs:label "Slack"@en ; + skos:prefLabel "Slack"@en ; + skos:definition "Support via Slack channel"@en ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; + rdfs:isDefinedBy . + +dprod:TeamsSupport + a dprod:SupportChannelType ; + rdfs:label "Microsoft Teams"@en ; + skos:prefLabel "Microsoft Teams"@en ; + skos:definition "Support via Microsoft Teams channel"@en ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; + rdfs:isDefinedBy . + +dprod:TicketSupport + a dprod:SupportChannelType ; + rdfs:label "Ticket System"@en ; + skos:prefLabel "Ticket System"@en ; + skos:definition "Support via ticketing system (JIRA, ServiceNow, etc.)"@en ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; + rdfs:isDefinedBy . + +dprod:DocumentationSupport + a dprod:SupportChannelType ; + rdfs:label "Documentation"@en ; + skos:prefLabel "Documentation"@en ; + skos:definition "Self-service support via documentation and FAQs"@en ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; + rdfs:isDefinedBy . + + +# ============================================================================== +# SUPPORT SCOPE VOCABULARY +# ============================================================================== + +dprod:SupportScopeScheme + a skos:ConceptScheme ; + rdfs:label "Support Scopes"@en ; + skos:definition "Scopes of support coverage for channels"@en ; + skos:hasTopConcept dprod:InteractiveSupport, dprod:IssueResolution, + dprod:Announcements, dprod:SelfService ; + rdfs:isDefinedBy . + +dprod:SupportScope + a owl:Class ; + rdfs:label "Support Scope"@en ; + skos:definition "Scope of support coverage"@en ; + rdfs:subClassOf skos:Concept ; + rdfs:isDefinedBy . + +dprod:InteractiveSupport + a dprod:SupportScope ; + rdfs:label "Interactive"@en ; + skos:prefLabel "Interactive"@en ; + skos:definition "Real-time Q&A and troubleshooting support"@en ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; + rdfs:isDefinedBy . + +dprod:IssueResolution + a dprod:SupportScope ; + rdfs:label "Issue Resolution"@en ; + skos:prefLabel "Issue Resolution"@en ; + skos:definition "Bug reports and incident handling"@en ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; + rdfs:isDefinedBy . + +dprod:Announcements + a dprod:SupportScope ; + rdfs:label "Announcements"@en ; + skos:prefLabel "Announcements"@en ; + skos:definition "One-way notifications about changes and updates"@en ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; + rdfs:isDefinedBy . + +dprod:SelfService + a dprod:SupportScope ; + rdfs:label "Self Service"@en ; + skos:prefLabel "Self Service"@en ; + skos:definition "Documentation and FAQ resources"@en ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; + rdfs:isDefinedBy . + + +# ============================================================================== +# ODRL PROFILE DECLARATION +# ============================================================================== + + + a odrl:Profile, skos:ConceptScheme ; + rdfs:label "DPROD ODRL Profile"@en ; + skos:definition "ODRL profile for DPROD Data Contract Ontology defining custom actions and promise-based commitments"@en ; + dct:description "Extends ODRL Core with promise-based patterns for bilateral data contracts, distinguishing provider obligations from consumer restrictions"@en ; + dct:creator "EKGF DPROD Working Group" ; + dct:created "2025-10-30"^^xsd:date ; + dct:modified "2025-12-18"^^xsd:date ; + owl:versionInfo "9.0.0" ; + rdfs:seeAlso ; + skos:note """This profile defines: + + Core Classes: + - dprod:DataOffer: Provider's standing offer (extends odrl:Offer) - not binding until accepted + - dprod:DataContract: Bilateral agreement (extends odrl:Agreement) - binding on both parties + - dprod:Promise: Custom Rule subclass for commitments (disjoint with odrl:Duty, odrl:Permission, odrl:Prohibition) + - dprod:ProviderPromise, dprod:ConsumerPromise: Role-specific promise types + - dprod:ProviderTimelinessPromise, dprod:ProviderSchemaPromise, dprod:ProviderChangeNotificationPromise, dprod:ProviderTerminationNoticePromise: Specialized provider promises + + Data Access Actions (Consumer Permissions): + - dprod:query (includedIn odrl:read): Execute queries against data service + - dprod:download (includedIn odrl:reproduce): Download data for local storage + - dprod:stream (includedIn odrl:stream): Receive real-time data feeds + - dprod:access (includedIn odrl:use): General access to data asset + + Data Transformation Actions (Consumer Permissions): + - dprod:deriveInsights (includedIn odrl:derive): Create analytics from data + - dprod:aggregate (includedIn odrl:aggregate): Combine with other data sources + - dprod:anonymize (includedIn odrl:anonymize): Remove PII before further use + - dprod:enrich (includedIn odrl:modify): Add value or annotations to data + + Distribution Actions (Consumer Permissions): + - dprod:redistribute (includedIn odrl:distribute): Share with third parties + - dprod:republish (includedIn odrl:reproduce): Publish derived datasets + - dprod:shareInternally (includedIn odrl:distribute): Share within organization + + Provider Obligation Actions: + - dprod:deliverOnSchedule (includedIn odrl:inform): Deliver per agreed schedule + - dprod:maintainSchema (includedIn odrl:inform): Maintain schema conformance + - dprod:maintainQuality (includedIn odrl:inform): Maintain data quality standards + - dprod:notifyChange (includedIn odrl:inform): Notify of breaking changes + - dprod:notifyTermination (includedIn odrl:inform): Provide termination notice + - dprod:provideSupport (includedIn odrl:inform): Provide technical support + + Consumer Obligation Actions: + - dprod:complyWithTerms (includedIn odrl:acceptTracking): Comply with usage terms + - dprod:deleteOnExpiry (includedIn odrl:delete): Delete data when contract expires + - dprod:reportUsage (includedIn odrl:inform): Report usage metrics + - dprod:provideAttribution (includedIn odrl:attribute): Attribute data source + - dprod:restrictPurpose (includedIn odrl:use): Restrict to declared purpose + + Policies using this profile should declare: odrl:profile + """@en . + + +# ============================================================================== +# USAGE PATTERNS DOCUMENTATION +# ============================================================================== + + + a skos:ConceptScheme ; + rdfs:label "DPROD Usage Patterns"@en ; + skos:note """ + DPROD v8.0 Usage for Data Providers: + + 1. Create DataOffer with odrl:assigner (provider's standing offer) + 2. Use odrl:target to specify data resources (dcat:Distribution, dcat:DataService, dprod:DataProduct) + 3. Add dprod:providerPromise instances: + - ProviderTimelinessPromise with dprod:hasSchedule (iCal or schema.org) + - ProviderSchemaPromise with odrl:target (dataset) + dprod:requiresConformanceTo (SHACL shape/standard) + - ProviderChangeNotificationPromise for general alerts + - ProviderTerminationNoticePromise with dprod:noticePeriod (time:Interval) + 4. Add dprod:consumerPromise instances for usage restrictions + 5. Use dprod:hasEffectivePeriod for offer validity period + 6. Use standard DCAT properties: dcat:version, dcat:previousVersion, adms:status + + For consumers accepting offers: + - Create DataContract extending the DataOffer + - Use prov:wasDerivedFrom to link to the accepted DataOffer + - Specify odrl:assignee (the consumer) + + Provenance patterns: + - prov:wasDerivedFrom: Subscription derived from offer (acceptance event) + - prov:wasRevisionOf: Offer revision/amendment (same offer evolved) + - prov:wasGeneratedBy: Creation activity tracking + + Contract versioning patterns: + - dprod:supersedes: New contract completely replaces previous version (superseded contract becomes Expired/Cancelled) + Example: Annual renewal with updated SLAs + - dprod:amends: Amendment/addendum extends existing contract (both remain Active simultaneously) + Example: Adding new compliance requirements to existing agreement + + Suitable for both internal organizational data sharing and external data marketplaces. + """@en . diff --git a/dprod-contracts/requirements.txt b/dprod-contracts/requirements.txt new file mode 100644 index 0000000..4e9b920 --- /dev/null +++ b/dprod-contracts/requirements.txt @@ -0,0 +1,4 @@ +rdflib>=7.0.0 +isodate>=0.7.0 +pyparsing>=3.2.0 +pyshacl>=0.25.0 From a60deca3e77b39c76bf6094123150fcb0637f33a Mon Sep 17 00:00:00 2001 From: tonys Date: Thu, 29 Jan 2026 17:08:22 +0000 Subject: [PATCH 02/10] Align dprod-contracts.ttl style with dprod-ontology.ttl conventions Reformats the contracts ontology to match the styling of the main DPROD ontology: 2-space indentation, header comments block, @base declaration, Dublin Core annotation property declarations, rdfs:Class alongside owl:Class, rdf:Property alongside owl property types, dct:description instead of skos:definition, rdfs:comment instead of skos:note, lowercase rdfs:label without @en, prefix-form rdfs:isDefinedBy, and period terminator on its own line. Co-Authored-By: Claude Opus 4.5 --- dprod-contracts/dprod-contracts.ttl | 1677 ++++++++++++++------------- 1 file changed, 848 insertions(+), 829 deletions(-) diff --git a/dprod-contracts/dprod-contracts.ttl b/dprod-contracts/dprod-contracts.ttl index 8c25ed8..f729441 100644 --- a/dprod-contracts/dprod-contracts.ttl +++ b/dprod-contracts/dprod-contracts.ttl @@ -1,1052 +1,1071 @@ -@prefix dprod: . -@prefix dcat: . -@prefix dct: . -@prefix odrl: . -@prefix prov: . -@prefix org: . -@prefix skos: . -@prefix rdfs: . -@prefix owl: . -@prefix xsd: . -@prefix time: . -@prefix adms: . +# baseURI: https://ekgf.github.io/dprod/contracts +# imports: http://www.w3.org/ns/dcat# +# imports: http://www.w3.org/ns/odrl/2/ +# imports: http://www.w3.org/ns/prov# +# imports: http://www.w3.org/ns/org# +# imports: http://www.w3.org/2006/time# +# prefix: dprod + +@base . +@prefix dprod: . +@prefix dcat: . +@prefix dct: . +@prefix odrl: . +@prefix prov: . +@prefix org: . +@prefix skos: . +@prefix rdfs: . +@prefix owl: . +@prefix rdf: . +@prefix xsd: . +@prefix time: . +@prefix adms: . @prefix schema: . - -# ============================================================================== -# ONTOLOGY DECLARATION -# ============================================================================== +# Since Dublin Core is not an ontology, declare here that the properties used are to be treated as AnnotationProperties in OWL +dct:description a owl:AnnotationProperty . +dct:creator a owl:AnnotationProperty . +dct:created a owl:AnnotationProperty . +dct:modified a owl:AnnotationProperty . - a owl:Ontology ; - rdfs:label "DPROD Data Contracts Ontology"@en ; - dct:title "DPROD Data Contracts Ontology"@en ; - dct:description "A semantic web ontology for formalizing bilateral data agreements between providers and consumers using W3C standards (RDF, OWL, SHACL, ODRL, DCAT)."@en ; - dct:creator "EKGF DPROD Working Group" ; - dct:created "2025-10-30"^^xsd:date ; - dct:modified "2025-01-08"^^xsd:date ; - owl:versionInfo "9.0.0" ; - owl:versionIRI ; - owl:imports , - , - , - , - ; - rdfs:seeAlso . - - -# ============================================================================== -# CORE CLASSES - Contract & Offer Classes -# ============================================================================== + a owl:Ontology ; + dct:title "DPROD Data Contracts Ontology"@en ; + rdfs:label "DPROD data contracts ontology"@en ; + dct:description "A semantic web ontology for formalizing bilateral data agreements between providers and consumers using W3C standards (RDF, OWL, SHACL, ODRL, DCAT)."@en ; + dct:creator "EKGF DPROD Working Group" ; + dct:created "2025-10-30"^^xsd:date ; + dct:modified "2025-01-08"^^xsd:date ; + owl:versionInfo "9.0.0" ; + owl:versionIRI ; + owl:imports dcat:, odrl:, prov:, org:, time: ; + rdfs:seeAlso ; +. + + +############################# Contract & Offer Classes ######################### dprod:DataContract - a owl:Class ; - rdfs:label "Data Contract"@en ; - skos:definition "Bilateral agreement establishing binding obligations between data provider (assigner) and consumer (assignee), formed when a consumer accepts a DataOffer."@en ; - rdfs:subClassOf odrl:Agreement ; - rdfs:isDefinedBy ; - skos:note "Extends odrl:Agreement to represent accepted terms. Both parties are bound by their respective promises. Use odrl:assigner for provider and odrl:assignee for consumer."@en ; - skos:example "An executed agreement for daily customer data updates, with provider committed to 6am delivery and consumer bound by usage restrictions"@en . + a owl:Class, rdfs:Class ; + dct:description + "Bilateral agreement establishing binding obligations between data provider (assigner) and consumer (assignee), formed when a consumer accepts a DataOffer."@en ; + rdfs:comment "Extends odrl:Agreement to represent accepted terms. Both parties are bound by their respective promises. Use odrl:assigner for provider and odrl:assignee for consumer."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "data contract" ; + rdfs:subClassOf odrl:Agreement ; +. dprod:DataOffer - a owl:Class ; - rdfs:label "Data Offer"@en ; - skos:definition "Provider's standing offer containing proposed terms, promises, and constraints available for consumer acceptance. Becomes binding upon acceptance to form a DataContract."@en ; - rdfs:subClassOf odrl:Offer ; - rdfs:isDefinedBy ; - skos:note "Represents the provider's proposed terms, published for discovery. Not binding until accepted. Use odrl:assigner to specify the offering party."@en ; - skos:example "A published offer for daily customer data updates via REST API with 6am refresh schedule, including timeliness and schema promises"@en . + a owl:Class, rdfs:Class ; + dct:description + "Provider's standing offer containing proposed terms, promises, and constraints available for consumer acceptance. Becomes binding upon acceptance to form a DataContract."@en ; + rdfs:comment "Represents the provider's proposed terms, published for discovery. Not binding until accepted. Use odrl:assigner to specify the offering party."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "data offer" ; + rdfs:subClassOf odrl:Offer ; +. -# ============================================================================== -# CORE CLASSES - Promise Classes -# ============================================================================== +############################# Promise Classes ######################### dprod:Promise - a owl:Class ; - rdfs:label "Promise"@en ; - skos:definition "Commitment from one party to another in a data contract"@en ; - rdfs:subClassOf odrl:Rule ; - owl:disjointWith odrl:Duty, odrl:Permission, odrl:Prohibition ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note """Base class for all commitments - service levels, quality guarantees, usage compliance, etc. - Use odrl:action to specify the type of commitment using DPROD actions. - Provider actions: dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport. - Consumer actions: dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, dprod:provideAttribution, dprod:restrictPurpose. - """@en . + a owl:Class, rdfs:Class ; + dct:description "Commitment from one party to another in a data contract"@en ; + rdfs:comment + "Base class for all commitments - service levels, quality guarantees, usage compliance, etc. Use odrl:action to specify the type of commitment using DPROD actions."@en ; + rdfs:comment + "Provider actions: dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport. Consumer actions: dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, dprod:provideAttribution, dprod:restrictPurpose."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "promise" ; + rdfs:subClassOf odrl:Rule ; + owl:disjointWith odrl:Duty, odrl:Permission, odrl:Prohibition ; + skos:inScheme ; +. dprod:ProviderPromise - a owl:Class ; - rdfs:label "Provider Promise"@en ; - skos:definition "Promise made by data providers about service delivery or data quality"@en ; - rdfs:subClassOf dprod:Promise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Use for commitments about data provision, service levels, quality guarantees, and operational responsibilities. Use provider obligation actions: dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport."@en . + a owl:Class, rdfs:Class ; + dct:description "Promise made by data providers about service delivery or data quality"@en ; + rdfs:comment "Use for commitments about data provision, service levels, quality guarantees, and operational responsibilities. Use provider obligation actions: dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider promise" ; + rdfs:subClassOf dprod:Promise ; + skos:inScheme ; +. dprod:ConsumerPromise - a owl:Class ; - rdfs:label "Consumer Promise"@en ; - skos:definition "Promise made by data consumer to abide by usage terms, compliance requirements, and license agreements"@en ; - rdfs:subClassOf dprod:Promise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Use for commitments about usage compliance, attribution, redistribution limits, and confidentiality. Use consumer obligation actions: dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, dprod:provideAttribution, dprod:restrictPurpose."@en . + a owl:Class, rdfs:Class ; + dct:description "Promise made by data consumer to abide by usage terms, compliance requirements, and license agreements"@en ; + rdfs:comment "Use for commitments about usage compliance, attribution, redistribution limits, and confidentiality. Use consumer obligation actions: dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, dprod:provideAttribution, dprod:restrictPurpose."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "consumer promise" ; + rdfs:subClassOf dprod:Promise ; + skos:inScheme ; +. dprod:ProviderTimelinessPromise - a owl:Class ; - rdfs:label "Provider Timeliness Promise"@en ; - skos:definition "Timeliness promise made by data providers about time-based delivery commitments"@en ; - rdfs:subClassOf dprod:ProviderPromise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Specialized promise for time-based service delivery commitments. Use dprod:deliverOnSchedule action. This will often refer to a recurring schedule via dprod:hasSchedule."@en . + a owl:Class, rdfs:Class ; + dct:description "Timeliness promise made by data providers about time-based delivery commitments"@en ; + rdfs:comment "Specialized promise for time-based service delivery commitments. Use dprod:deliverOnSchedule action. This will often refer to a recurring schedule via dprod:hasSchedule."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider timeliness promise" ; + rdfs:subClassOf dprod:ProviderPromise ; + skos:inScheme ; +. dprod:ProviderSchemaPromise - a owl:Class ; - rdfs:label "Provider Schema Promise"@en ; - skos:definition "Promise made by data providers about schema conformance for a specific dataset or resource"@en ; - rdfs:subClassOf dprod:ProviderPromise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Use dprod:maintainSchema action. Use odrl:target to identify the specific dataset/distribution and dprod:requiresConformanceTo to reference the schema (SHACL shape, OWL ontology, etc.) it must conform to. This creates a contractual binding between a resource and a schema specification. The targeted resource should declare dct:conformsTo with the same schema. Typically specifies a constrained view or subset of the full dataset schema. The promised schema defines what consumers can rely upon, which may be more stable than the source schema."@en ; - skos:example "A promise with odrl:target pointing to :customerDataset and dprod:requiresConformanceTo pointing to CustomerDataShape.ttl commits the provider to deliver that specific dataset conforming to that shape."@en . + a owl:Class, rdfs:Class ; + dct:description "Promise made by data providers about schema conformance for a specific dataset or resource"@en ; + rdfs:comment + "Use dprod:maintainSchema action. Use odrl:target to identify the specific dataset/distribution and dprod:requiresConformanceTo to reference the schema (SHACL shape, OWL ontology, etc.) it must conform to. This creates a contractual binding between a resource and a schema specification. The targeted resource should declare dct:conformsTo with the same schema. Typically specifies a constrained view or subset of the full dataset schema. The promised schema defines what consumers can rely upon, which may be more stable than the source schema."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider schema promise" ; + rdfs:subClassOf dprod:ProviderPromise ; + skos:inScheme ; +. dprod:ProviderChangeNotificationPromise - a owl:Class ; - rdfs:label "Provider Change Notification Promise"@en ; - skos:definition "Change notification promise made by data providers about service delivery changes"@en ; - rdfs:subClassOf dprod:ProviderPromise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Use dprod:notifyChange action. Use for commitments that require notifying consumers about impending changes. Subclasses capture specific notice expectations such as termination lead time."@en . + a owl:Class, rdfs:Class ; + dct:description "Change notification promise made by data providers about service delivery changes"@en ; + rdfs:comment "Use dprod:notifyChange action. Use for commitments that require notifying consumers about impending changes. Subclasses capture specific notice expectations such as termination lead time."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider change notification promise" ; + rdfs:subClassOf dprod:ProviderPromise ; + skos:inScheme ; +. dprod:ProviderTerminationNoticePromise - a owl:Class ; - rdfs:label "Provider Termination Notice Promise"@en ; - skos:definition "Promise made by data providers to give advance notice before terminating a contract or introducing breaking changes."@en ; - rdfs:subClassOf dprod:ProviderChangeNotificationPromise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Use dprod:notifyTermination action. Capture required notice periods using dprod:noticePeriod. This distinguishes advance termination notifications from other change alerts."@en . + a owl:Class, rdfs:Class ; + dct:description "Promise made by data providers to give advance notice before terminating a contract or introducing breaking changes."@en ; + rdfs:comment "Use dprod:notifyTermination action. Capture required notice periods using dprod:noticePeriod. This distinguishes advance termination notifications from other change alerts."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider termination notice promise" ; + rdfs:subClassOf dprod:ProviderChangeNotificationPromise ; + skos:inScheme ; +. dprod:ProviderServiceLevelPromise - a owl:Class ; - rdfs:label "Provider Service Level Promise"@en ; - skos:definition "Promise with quantitative service level targets such as availability, latency, and throughput."@en ; - rdfs:subClassOf dprod:ProviderPromise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Use dprod:meetServiceLevel action. Attach quantitative targets via dprod:hasServiceLevelTarget. Each target specifies a metric, value, unit, and optional measurement period."@en ; - skos:example "A promise guaranteeing 99.9% monthly availability and p95 response time under 500ms."@en . + a owl:Class, rdfs:Class ; + dct:description "Promise with quantitative service level targets such as availability, latency, and throughput."@en ; + rdfs:comment "Use dprod:meetServiceLevel action. Attach quantitative targets via dprod:hasServiceLevelTarget. Each target specifies a metric, value, unit, and optional measurement period."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider service level promise" ; + rdfs:subClassOf dprod:ProviderPromise ; + skos:inScheme ; +. dprod:ProviderSupportPromise - a owl:Class ; - rdfs:label "Provider Support Promise"@en ; - skos:definition "Promise about technical support availability including channels, scope, and response times."@en ; - rdfs:subClassOf dprod:ProviderPromise ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Use dprod:provideSupport action. Specify support channels via dprod:hasSupportChannel with channel type, URL, scope, and response time targets."@en ; - skos:example "A promise providing Slack support with 4-hour response time and ticket system for issue resolution."@en . + a owl:Class, rdfs:Class ; + dct:description "Promise about technical support availability including channels, scope, and response times."@en ; + rdfs:comment "Use dprod:provideSupport action. Specify support channels via dprod:hasSupportChannel with channel type, URL, scope, and response time targets."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider support promise" ; + rdfs:subClassOf dprod:ProviderPromise ; + skos:inScheme ; +. -# ============================================================================== -# CORE CLASSES - SLA Target and Support Channel Classes -# ============================================================================== +############################# SLA Target & Support Channel Classes ######################### dprod:ServiceLevelTarget - a owl:Class ; - rdfs:label "Service Level Target"@en ; - skos:definition "A quantitative target for a specific service level metric."@en ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Captures metric type (dprod:slaMetric), numeric target (dprod:targetValue), unit of measurement (dprod:unit), and optional measurement period (dprod:measurementPeriod)."@en . + a owl:Class, rdfs:Class ; + dct:description "A quantitative target for a specific service level metric."@en ; + rdfs:comment "Captures metric type (dprod:slaMetric), numeric target (dprod:targetValue), unit of measurement (dprod:unit), and optional measurement period (dprod:measurementPeriod)."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "service level target" ; + skos:inScheme ; +. dprod:SupportChannel - a owl:Class ; - rdfs:label "Support Channel"@en ; - skos:definition "A communication channel for obtaining technical support."@en ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Specify channel type, URL, support scope, and response time target."@en . + a owl:Class, rdfs:Class ; + dct:description "A communication channel for obtaining technical support."@en ; + rdfs:comment "Specify channel type, URL, support scope, and response time target."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "support channel" ; + skos:inScheme ; +. -# ============================================================================== -# CORE CLASSES - Schedule Classes -# ============================================================================== +############################# Schedule Classes ######################### dprod:Schedule - a owl:Class ; - rdfs:label "Schedule"@en ; - skos:definition "Flexible schedule specification supporting multiple temporal formats"@en ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "Instances should be either schema:Schedule or dprod:ICalSchedule. Validation enforced by SHACL. For validity periods, use dprod:hasEffectivePeriod with time:Interval."@en . + a owl:Class, rdfs:Class ; + dct:description "Flexible schedule specification supporting multiple temporal formats"@en ; + rdfs:comment "Instances should be either schema:Schedule or dprod:ICalSchedule. Validation enforced by SHACL. For validity periods, use dprod:hasEffectivePeriod with time:Interval."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "schedule" ; + skos:inScheme ; +. dprod:ICalSchedule - a owl:Class ; - rdfs:label "iCal Schedule"@en ; - skos:definition "Schedule expressed using iCalendar RRULE format"@en ; - rdfs:isDefinedBy ; - skos:inScheme ; - skos:note "For complex recurring schedules using standard iCal RRULE syntax. Validation enforced by SHACL: must have exactly one dprod:icalRule."@en . + a owl:Class, rdfs:Class ; + dct:description "Schedule expressed using iCalendar RRULE format"@en ; + rdfs:comment "For complex recurring schedules using standard iCal RRULE syntax. Validation enforced by SHACL: must have exactly one dprod:icalRule."@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "iCal schedule" ; + skos:inScheme ; +. -# ============================================================================== -# ODRL ACTIONS - Data Access -# ============================================================================== +############################# ODRL Actions - Data Access ######################### dprod:DataAccessAction - a skos:Concept ; - rdfs:label "Data Access Action"@en ; - skos:prefLabel "Data Access Action"@en ; - skos:definition "Actions that allow consumers to access and retrieve data from the provider."@en ; - skos:inScheme ; - skos:topConceptOf ; - rdfs:isDefinedBy ; - skos:narrower dprod:query, dprod:download, dprod:stream, dprod:access . + a skos:Concept ; + dct:description "Actions that allow consumers to access and retrieve data from the provider."@en ; + skos:prefLabel "Data Access Action"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "data access action" ; + skos:inScheme ; + skos:topConceptOf ; + skos:narrower dprod:query, dprod:download, dprod:stream, dprod:access ; +. dprod:query - a odrl:Action, skos:Concept ; - rdfs:label "Query"@en ; - skos:prefLabel "query"@en ; - skos:definition "Execute queries against a data service to retrieve specific data subsets."@en ; - odrl:includedIn odrl:read ; - skos:broader dprod:DataAccessAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Execute queries against a data service to retrieve specific data subsets."@en ; + skos:prefLabel "query"@en ; + odrl:includedIn odrl:read ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "query" ; + skos:inScheme ; +. dprod:download - a odrl:Action, skos:Concept ; - rdfs:label "Download"@en ; - skos:prefLabel "download"@en ; - skos:definition "Download data assets for local storage and offline use."@en ; - odrl:includedIn odrl:reproduce ; - skos:broader dprod:DataAccessAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Download data assets for local storage and offline use."@en ; + skos:prefLabel "download"@en ; + odrl:includedIn odrl:reproduce ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "download" ; + skos:inScheme ; +. dprod:stream - a odrl:Action, skos:Concept ; - rdfs:label "Stream"@en ; - skos:prefLabel "stream"@en ; - skos:definition "Receive real-time data feeds or continuous data streams."@en ; - odrl:includedIn odrl:stream ; - skos:broader dprod:DataAccessAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Receive real-time data feeds or continuous data streams."@en ; + skos:prefLabel "stream"@en ; + odrl:includedIn odrl:stream ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "stream" ; + skos:inScheme ; +. dprod:access - a odrl:Action, skos:Concept ; - rdfs:label "Access"@en ; - skos:prefLabel "access"@en ; - skos:definition "General access to a data asset without specifying the access method."@en ; - odrl:includedIn odrl:use ; - skos:broader dprod:DataAccessAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "General access to a data asset without specifying the access method."@en ; + skos:prefLabel "access"@en ; + odrl:includedIn odrl:use ; + skos:broader dprod:DataAccessAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "access" ; + skos:inScheme ; +. -# ============================================================================== -# ODRL ACTIONS - Data Transformation -# ============================================================================== +############################# ODRL Actions - Data Transformation ######################### dprod:DataTransformationAction - a skos:Concept ; - rdfs:label "Data Transformation Action"@en ; - skos:prefLabel "Data Transformation Action"@en ; - skos:definition "Actions that allow consumers to transform, derive, or modify data."@en ; - skos:inScheme ; - skos:topConceptOf ; - rdfs:isDefinedBy ; - skos:narrower dprod:deriveInsights, dprod:aggregate, dprod:anonymize, dprod:enrich . + a skos:Concept ; + dct:description "Actions that allow consumers to transform, derive, or modify data."@en ; + skos:prefLabel "Data Transformation Action"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "data transformation action" ; + skos:inScheme ; + skos:topConceptOf ; + skos:narrower dprod:deriveInsights, dprod:aggregate, dprod:anonymize, dprod:enrich ; +. dprod:deriveInsights - a odrl:Action, skos:Concept ; - rdfs:label "Derive Insights"@en ; - skos:prefLabel "derive insights"@en ; - skos:definition "Create analytics, reports, or insights derived from the data asset."@en ; - odrl:includedIn odrl:derive ; - skos:broader dprod:DataTransformationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Create analytics, reports, or insights derived from the data asset."@en ; + skos:prefLabel "derive insights"@en ; + odrl:includedIn odrl:derive ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "derive insights" ; + skos:inScheme ; +. dprod:aggregate - a odrl:Action, skos:Concept ; - rdfs:label "Aggregate"@en ; - skos:prefLabel "aggregate"@en ; - skos:definition "Combine data with other data sources to create aggregated datasets."@en ; - odrl:includedIn odrl:aggregate ; - skos:broader dprod:DataTransformationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Combine data with other data sources to create aggregated datasets."@en ; + skos:prefLabel "aggregate"@en ; + odrl:includedIn odrl:aggregate ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "aggregate" ; + skos:inScheme ; +. dprod:anonymize - a odrl:Action, skos:Concept ; - rdfs:label "Anonymize"@en ; - skos:prefLabel "anonymize"@en ; - skos:definition "Remove personally identifiable information before further use or distribution."@en ; - odrl:includedIn odrl:anonymize ; - skos:broader dprod:DataTransformationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Remove personally identifiable information before further use or distribution."@en ; + skos:prefLabel "anonymize"@en ; + odrl:includedIn odrl:anonymize ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "anonymize" ; + skos:inScheme ; +. dprod:enrich - a odrl:Action, skos:Concept ; - rdfs:label "Enrich"@en ; - skos:prefLabel "enrich"@en ; - skos:definition "Add value, annotations, or additional attributes to data assets."@en ; - odrl:includedIn odrl:modify ; - skos:broader dprod:DataTransformationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Add value, annotations, or additional attributes to data assets."@en ; + skos:prefLabel "enrich"@en ; + odrl:includedIn odrl:modify ; + skos:broader dprod:DataTransformationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "enrich" ; + skos:inScheme ; +. -# ============================================================================== -# ODRL ACTIONS - Distribution -# ============================================================================== +############################# ODRL Actions - Distribution ######################### dprod:DistributionAction - a skos:Concept ; - rdfs:label "Distribution Action"@en ; - skos:prefLabel "Distribution Action"@en ; - skos:definition "Actions that allow consumers to distribute or share data with others."@en ; - skos:inScheme ; - skos:topConceptOf ; - rdfs:isDefinedBy ; - skos:narrower dprod:redistribute, dprod:republish, dprod:shareInternally . + a skos:Concept ; + dct:description "Actions that allow consumers to distribute or share data with others."@en ; + skos:prefLabel "Distribution Action"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "distribution action" ; + skos:inScheme ; + skos:topConceptOf ; + skos:narrower dprod:redistribute, dprod:republish, dprod:shareInternally ; +. dprod:redistribute - a odrl:Action, skos:Concept ; - rdfs:label "Redistribute"@en ; - skos:prefLabel "redistribute"@en ; - skos:definition "Share data assets with third parties outside the organization."@en ; - odrl:includedIn odrl:distribute ; - skos:broader dprod:DistributionAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Share data assets with third parties outside the organization."@en ; + skos:prefLabel "redistribute"@en ; + odrl:includedIn odrl:distribute ; + skos:broader dprod:DistributionAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "redistribute" ; + skos:inScheme ; +. dprod:republish - a odrl:Action, skos:Concept ; - rdfs:label "Republish"@en ; - skos:prefLabel "republish"@en ; - skos:definition "Publish derived datasets or data products based on the original data."@en ; - odrl:includedIn odrl:reproduce ; - skos:broader dprod:DistributionAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Publish derived datasets or data products based on the original data."@en ; + skos:prefLabel "republish"@en ; + odrl:includedIn odrl:reproduce ; + skos:broader dprod:DistributionAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "republish" ; + skos:inScheme ; +. dprod:shareInternally - a odrl:Action, skos:Concept ; - rdfs:label "Share Internally"@en ; - skos:prefLabel "share internally"@en ; - skos:definition "Share data assets within the organization or organizational unit."@en ; - odrl:includedIn odrl:distribute ; - skos:broader dprod:DistributionAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Share data assets within the organization or organizational unit."@en ; + skos:prefLabel "share internally"@en ; + odrl:includedIn odrl:distribute ; + skos:broader dprod:DistributionAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "share internally" ; + skos:inScheme ; +. -# ============================================================================== -# ODRL ACTIONS - Provider Obligations -# ============================================================================== +############################# ODRL Actions - Provider Obligations ######################### dprod:ProviderObligationAction - a skos:Concept ; - rdfs:label "Provider Obligation Action"@en ; - skos:prefLabel "Provider Obligation Action"@en ; - skos:definition "Actions representing obligations the provider commits to fulfill."@en ; - skos:inScheme ; - skos:topConceptOf ; - rdfs:isDefinedBy ; - skos:narrower dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, - dprod:meetServiceLevel, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport . + a skos:Concept ; + dct:description "Actions representing obligations the provider commits to fulfill."@en ; + skos:prefLabel "Provider Obligation Action"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provider obligation action" ; + skos:inScheme ; + skos:topConceptOf ; + skos:narrower dprod:deliverOnSchedule, dprod:maintainSchema, dprod:maintainQuality, + dprod:meetServiceLevel, dprod:notifyChange, dprod:notifyTermination, dprod:provideSupport ; +. dprod:deliverOnSchedule - a odrl:Action, skos:Concept ; - rdfs:label "Deliver on Schedule"@en ; - skos:prefLabel "deliver on schedule"@en ; - skos:definition "Deliver data according to the agreed schedule specified in the contract."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ProviderObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Deliver data according to the agreed schedule specified in the contract."@en ; + skos:prefLabel "deliver on schedule"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "deliver on schedule" ; + skos:inScheme ; +. dprod:maintainSchema - a odrl:Action, skos:Concept ; - rdfs:label "Maintain Schema"@en ; - skos:prefLabel "maintain schema"@en ; - skos:definition "Maintain schema conformance as specified in the contract."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ProviderObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Maintain schema conformance as specified in the contract."@en ; + skos:prefLabel "maintain schema"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "maintain schema" ; + skos:inScheme ; +. dprod:maintainQuality - a odrl:Action, skos:Concept ; - rdfs:label "Maintain Quality"@en ; - skos:prefLabel "maintain quality"@en ; - skos:definition "Maintain data quality standards as specified in the contract."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ProviderObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Maintain data quality standards as specified in the contract."@en ; + skos:prefLabel "maintain quality"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "maintain quality" ; + skos:inScheme ; +. dprod:meetServiceLevel - a odrl:Action, skos:Concept ; - rdfs:label "Meet Service Level"@en ; - skos:prefLabel "meet service level"@en ; - skos:definition "Meet the quantitative service level targets specified in the contract."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ProviderObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Meet the quantitative service level targets specified in the contract."@en ; + skos:prefLabel "meet service level"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "meet service level" ; + skos:inScheme ; +. dprod:notifyChange - a odrl:Action, skos:Concept ; - rdfs:label "Notify Change"@en ; - skos:prefLabel "notify change"@en ; - skos:definition "Notify consumers of breaking changes, schema updates, or service modifications."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ProviderObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Notify consumers of breaking changes, schema updates, or service modifications."@en ; + skos:prefLabel "notify change"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "notify change" ; + skos:inScheme ; +. dprod:notifyTermination - a odrl:Action, skos:Concept ; - rdfs:label "Notify Termination"@en ; - skos:prefLabel "notify termination"@en ; - skos:definition "Provide advance notice before terminating the contract or discontinuing the service."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ProviderObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Provide advance notice before terminating the contract or discontinuing the service."@en ; + skos:prefLabel "notify termination"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "notify termination" ; + skos:inScheme ; +. dprod:provideSupport - a odrl:Action, skos:Concept ; - rdfs:label "Provide Support"@en ; - skos:prefLabel "provide support"@en ; - skos:definition "Provide technical support for data access and integration issues."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ProviderObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Provide technical support for data access and integration issues."@en ; + skos:prefLabel "provide support"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ProviderObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provide support" ; + skos:inScheme ; +. -# ============================================================================== -# ODRL ACTIONS - Consumer Obligations -# ============================================================================== +############################# ODRL Actions - Consumer Obligations ######################### dprod:ConsumerObligationAction - a skos:Concept ; - rdfs:label "Consumer Obligation Action"@en ; - skos:prefLabel "Consumer Obligation Action"@en ; - skos:definition "Actions representing obligations the consumer commits to fulfill."@en ; - skos:inScheme ; - skos:topConceptOf ; - rdfs:isDefinedBy ; - skos:narrower dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, - dprod:provideAttribution, dprod:restrictPurpose . + a skos:Concept ; + dct:description "Actions representing obligations the consumer commits to fulfill."@en ; + skos:prefLabel "Consumer Obligation Action"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "consumer obligation action" ; + skos:inScheme ; + skos:topConceptOf ; + skos:narrower dprod:complyWithTerms, dprod:deleteOnExpiry, dprod:reportUsage, + dprod:provideAttribution, dprod:restrictPurpose ; +. dprod:complyWithTerms - a odrl:Action, skos:Concept ; - rdfs:label "Comply with Terms"@en ; - skos:prefLabel "comply with terms"@en ; - skos:definition "Accept and comply with all usage terms specified in the contract."@en ; - odrl:includedIn odrl:acceptTracking ; - skos:broader dprod:ConsumerObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Accept and comply with all usage terms specified in the contract."@en ; + skos:prefLabel "comply with terms"@en ; + odrl:includedIn odrl:acceptTracking ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "comply with terms" ; + skos:inScheme ; +. dprod:deleteOnExpiry - a odrl:Action, skos:Concept ; - rdfs:label "Delete on Expiry"@en ; - skos:prefLabel "delete on expiry"@en ; - skos:definition "Delete all copies of the data when the contract expires or is terminated."@en ; - odrl:includedIn odrl:delete ; - skos:broader dprod:ConsumerObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Delete all copies of the data when the contract expires or is terminated."@en ; + skos:prefLabel "delete on expiry"@en ; + odrl:includedIn odrl:delete ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "delete on expiry" ; + skos:inScheme ; +. dprod:reportUsage - a odrl:Action, skos:Concept ; - rdfs:label "Report Usage"@en ; - skos:prefLabel "report usage"@en ; - skos:definition "Report usage metrics and access patterns to the data provider."@en ; - odrl:includedIn odrl:inform ; - skos:broader dprod:ConsumerObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Report usage metrics and access patterns to the data provider."@en ; + skos:prefLabel "report usage"@en ; + odrl:includedIn odrl:inform ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "report usage" ; + skos:inScheme ; +. dprod:provideAttribution - a odrl:Action, skos:Concept ; - rdfs:label "Provide Attribution"@en ; - skos:prefLabel "provide attribution"@en ; - skos:definition "Provide proper attribution to the data source in any derived works or publications."@en ; - odrl:includedIn odrl:attribute ; - skos:broader dprod:ConsumerObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Provide proper attribution to the data source in any derived works or publications."@en ; + skos:prefLabel "provide attribution"@en ; + odrl:includedIn odrl:attribute ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "provide attribution" ; + skos:inScheme ; +. dprod:restrictPurpose - a odrl:Action, skos:Concept ; - rdfs:label "Restrict Purpose"@en ; - skos:prefLabel "restrict purpose"@en ; - skos:definition "Restrict data usage to the declared purpose specified in the contract."@en ; - odrl:includedIn odrl:use ; - skos:broader dprod:ConsumerObligationAction ; - rdfs:isDefinedBy ; - skos:inScheme . + a odrl:Action, skos:Concept ; + dct:description "Restrict data usage to the declared purpose specified in the contract."@en ; + skos:prefLabel "restrict purpose"@en ; + odrl:includedIn odrl:use ; + skos:broader dprod:ConsumerObligationAction ; + rdfs:isDefinedBy dprod: ; + rdfs:label "restrict purpose" ; + skos:inScheme ; +. -# ============================================================================== -# PROPERTIES - Promise Linking -# ============================================================================== +############################# Promise Linking Properties ################ dprod:hasPromise - a owl:ObjectProperty ; - rdfs:label "has promise"@en ; - rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; - rdfs:range dprod:Promise ; - dct:description "Links a contract to any binding commitment (promise), whether undertaken by provider or consumer. Use specific subproperties (providerPromise, consumerPromise) when the commitment direction is known."@en ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range dprod:Promise ; + dct:description "Links a contract to any binding commitment (promise), whether undertaken by provider or consumer. Use specific subproperties (providerPromise, consumerPromise) when the commitment direction is known."@en ; + rdfs:label "has promise" ; +. dprod:providerPromise - a owl:ObjectProperty ; - rdfs:label "provider promise"@en ; - rdfs:subPropertyOf dprod:hasPromise ; - rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; - rdfs:range dprod:ProviderPromise ; - dct:description "Affirmative obligations undertaken by the data provider, including warranties about data quality, service level commitments (SLAs), delivery timeliness, schema stability, and change notification requirements. Represents what the provider commits to deliver or maintain."@en ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:subPropertyOf dprod:hasPromise ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range dprod:ProviderPromise ; + dct:description "Affirmative obligations undertaken by the data provider, including warranties about data quality, service level commitments (SLAs), delivery timeliness, schema stability, and change notification requirements. Represents what the provider commits to deliver or maintain."@en ; + rdfs:label "provider promise" ; +. dprod:consumerPromise - a owl:ObjectProperty ; - rdfs:label "consumer promise"@en ; - rdfs:subPropertyOf dprod:hasPromise ; - rdfs:domain dprod:DataContract ; - rdfs:range dprod:ConsumerPromise ; - dct:description "Restrictive covenants and use obligations binding the consumer, including permitted/prohibited uses, compliance requirements, attribution obligations, redistribution limits, and confidentiality terms. Represents what the consumer agrees to do or refrain from doing."@en ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:subPropertyOf dprod:hasPromise ; + rdfs:domain dprod:DataContract ; + rdfs:range dprod:ConsumerPromise ; + dct:description "Restrictive covenants and use obligations binding the consumer, including permitted/prohibited uses, compliance requirements, attribution obligations, redistribution limits, and confidentiality terms. Represents what the consumer agrees to do or refrain from doing."@en ; + rdfs:label "consumer promise" ; +. -# ============================================================================== -# PROPERTIES - Data Product Linking -# ============================================================================== +############################# Data Product Linking Properties ################ dprod:dataContract - a owl:ObjectProperty ; - rdfs:label "data contract"@en ; - rdfs:domain dprod:DataProduct ; - rdfs:range dprod:DataContract ; - rdfs:subPropertyOf odrl:hasPolicy ; - dct:description "Contract(s) governing a data product's inputs, outputs, or access services."@en ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:DataProduct ; + rdfs:range dprod:DataContract ; + rdfs:subPropertyOf odrl:hasPolicy ; + dct:description "Contract(s) governing a data product's inputs, outputs, or access services."@en ; + rdfs:label "data contract" ; +. dprod:contractStatus - a owl:ObjectProperty, owl:FunctionalProperty ; - rdfs:label "contract status"@en ; - skos:definition "Current lifecycle status of a data contract or offer"@en ; - rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; - rdfs:range dprod:ContractStatus ; - rdfs:subPropertyOf adms:status ; - dct:description "Lifecycle status indicating whether the contract or offer is Pending, Active, Expired, or Cancelled. Values must be instances of dprod:ContractStatus from the dprod:ContractStatusScheme."@en ; - rdfs:isDefinedBy ; - skos:note "Functional property - each contract/offer has at most one status value at any given time."@en . + a rdf:Property, owl:ObjectProperty, owl:FunctionalProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range dprod:ContractStatus ; + rdfs:subPropertyOf adms:status ; + dct:description + "Lifecycle status indicating whether the contract or offer is Pending, Active, Expired, or Cancelled. Values must be instances of dprod:ContractStatus from the dprod:ContractStatusScheme."@en ; + rdfs:comment "Functional property - each contract/offer has at most one status value at any given time."@en ; + rdfs:label "contract status" ; +. -# ============================================================================== -# PROPERTIES - Contract Versioning & Provenance -# ============================================================================== +############################# Contract Versioning & Provenance Properties ################ dprod:supersedes - a owl:ObjectProperty ; - rdfs:label "supersedes"@en ; - skos:definition "This contract supersedes and replaces a previous contract"@en ; - rdfs:subPropertyOf prov:wasRevisionOf, dct:replaces ; - rdfs:domain dprod:DataContract ; - rdfs:range dprod:DataContract ; - dct:description "Links a contract to the previous version it supersedes. Use for contract renewals where the new contract completely replaces the old one. The superseded contract typically transitions to Expired or Cancelled status."@en ; - rdfs:isDefinedBy ; - skos:note "Enables version tracking: Contract v2.0 supersedes Contract v1.0. Useful for understanding contract evolution and maintaining audit trails."@en ; - skos:example """ - # Contract renewal: - :contract2025 a dprod:DataContract ; - dprod:supersedes :contract2024 ; - dcat:version "2.0" ; - rdfs:comment "Annual renewal with updated SLAs" . - - :contract2024 dprod:contractStatus dprod:ContractStatusExpired . - """@en . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:subPropertyOf prov:wasRevisionOf, dct:replaces ; + rdfs:domain dprod:DataContract ; + rdfs:range dprod:DataContract ; + dct:description "Links a contract to the previous version it supersedes. Use for contract renewals where the new contract completely replaces the old one. The superseded contract typically transitions to Expired or Cancelled status."@en ; + rdfs:comment "Enables version tracking: Contract v2.0 supersedes Contract v1.0. Useful for understanding contract evolution and maintaining audit trails."@en ; + rdfs:label "supersedes" ; +. dprod:amends - a owl:ObjectProperty ; - rdfs:label "amends"@en ; - skos:definition "This contract amends or extends an existing active contract"@en ; - rdfs:subPropertyOf prov:wasRevisionOf ; - rdfs:domain dprod:DataContract ; - rdfs:range dprod:DataContract ; - dct:description "Links an amendment/addendum to the base contract it modifies. Use when both contracts remain active simultaneously - the amendment adds to or modifies specific terms without replacing the entire base contract."@en ; - rdfs:isDefinedBy ; - skos:note "Enables tracking of contract amendments and addendums. Multiple amendments can reference the same base contract. Both the base contract and amendments can be Active simultaneously."@en ; - skos:example """ - # Base contract with multiple amendments: - :baseContract a dprod:DataContract ; - dcat:version "1.0" ; - dprod:contractStatus dprod:ContractStatusActive . - - :amendment1 a dprod:DataContract ; - dprod:amends :baseContract ; - dcat:version "1.1-amendment" ; - rdfs:comment "Adds GDPR compliance requirements" ; - dprod:contractStatus dprod:ContractStatusActive . - - :amendment2 a dprod:DataContract ; - dprod:amends :baseContract ; - dcat:version "1.2-amendment" ; - rdfs:comment "Adds new dataset to scope" ; - dprod:contractStatus dprod:ContractStatusActive . - """@en . - - -# ============================================================================== -# PROPERTIES - Temporal Properties -# ============================================================================== + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:subPropertyOf prov:wasRevisionOf ; + rdfs:domain dprod:DataContract ; + rdfs:range dprod:DataContract ; + dct:description "Links an amendment/addendum to the base contract it modifies. Use when both contracts remain active simultaneously - the amendment adds to or modifies specific terms without replacing the entire base contract."@en ; + rdfs:comment "Enables tracking of contract amendments and addendums. Multiple amendments can reference the same base contract. Both the base contract and amendments can be Active simultaneously."@en ; + rdfs:label "amends" ; +. + + +############################# Temporal Properties ################ dprod:hasEffectivePeriod - a owl:ObjectProperty ; - rdfs:label "has effective period"@en ; - skos:definition "Effective period (convenience property aligned with dcterms:temporal)"@en ; - rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract dprod:Promise ) ] ; - rdfs:range time:Interval ; - rdfs:subPropertyOf dct:temporal ; - rdfs:isDefinedBy ; - skos:note "For structured time intervals only. Use time:hasBeginning and time:hasEnd on the Interval. For textual period expressions, use dcterms:temporal directly on the offer or contract."@en . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract dprod:Promise ) ] ; + rdfs:range time:Interval ; + rdfs:subPropertyOf dct:temporal ; + dct:description "Effective period (convenience property aligned with dcterms:temporal)"@en ; + rdfs:comment "For structured time intervals only. Use time:hasBeginning and time:hasEnd on the Interval. For textual period expressions, use dcterms:temporal directly on the offer or contract."@en ; + rdfs:label "has effective period" ; +. dprod:noticePeriod - a owl:ObjectProperty ; - rdfs:label "notice period"@en ; - skos:definition "Advance notice interval that must elapse before a termination or breaking change takes effect."@en ; - rdfs:domain dprod:ProviderTerminationNoticePromise ; - rdfs:range time:Interval ; - rdfs:subPropertyOf dct:temporal ; - rdfs:isDefinedBy ; - skos:note "Describe lead time requirements by providing time:hasBeginning and time:hasEnd values on the interval (e.g., 90-day notice)."@en . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ProviderTerminationNoticePromise ; + rdfs:range time:Interval ; + rdfs:subPropertyOf dct:temporal ; + dct:description + "Advance notice interval that must elapse before a termination or breaking change takes effect."@en ; + rdfs:comment "Describe lead time requirements by providing time:hasBeginning and time:hasEnd values on the interval (e.g., 90-day notice)."@en ; + rdfs:label "notice period" ; +. dprod:hasSchedule - a owl:ObjectProperty ; - rdfs:label "has schedule"@en ; - skos:definition "Schedule specification for provider promises with flexible format support"@en ; - rdfs:domain dprod:ProviderTimelinessPromise ; - rdfs:range dprod:Schedule ; - rdfs:subPropertyOf dct:temporal ; - rdfs:isDefinedBy ; - skos:note "Accepts time:TemporalEntity, schema:Schedule, or dprod:ICalSchedule formats"@en . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ProviderTimelinessPromise ; + rdfs:range dprod:Schedule ; + rdfs:subPropertyOf dct:temporal ; + dct:description "Schedule specification for provider promises with flexible format support"@en ; + rdfs:comment "Accepts time:TemporalEntity, schema:Schedule, or dprod:ICalSchedule formats"@en ; + rdfs:label "has schedule" ; +. dprod:requiresConformanceTo - a owl:ObjectProperty ; - rdfs:label "requires conformance to"@en ; - skos:definition "Schema, model, or standard that the targeted resource must conform to"@en ; - rdfs:domain dprod:ProviderSchemaPromise ; - rdfs:range dct:Standard ; - dct:description "Specifies the schema/standard that the resource identified by odrl:target must conform to. Use alongside odrl:target to bind a specific dataset/distribution to a schema requirement. The targeted resource should declare dct:conformsTo with the same schema. Typically references SHACL shapes, OWL ontologies, or industry standards (e.g., FIBO, schema.org profiles)."@en ; - rdfs:isDefinedBy ; - skos:note "Works in conjunction with odrl:target. The promise targets a specific dataset (via odrl:target) and requires it to conform to a schema (via dprod:requiresConformanceTo). The referenced schema becomes a contractual commitment."@en ; - skos:example """ - # Promise binds specific dataset to schema: - :schemaPromise a dprod:ProviderSchemaPromise ; - odrl:action dprod:maintainSchema ; - odrl:target :customerDataset ; - dprod:requiresConformanceTo . - """@en . - - -# ============================================================================== -# PROPERTIES - Service Level Properties -# ============================================================================== + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ProviderSchemaPromise ; + rdfs:range dct:Standard ; + dct:description + "Specifies the schema/standard that the resource identified by odrl:target must conform to. Use alongside odrl:target to bind a specific dataset/distribution to a schema requirement. The targeted resource should declare dct:conformsTo with the same schema. Typically references SHACL shapes, OWL ontologies, or industry standards (e.g., FIBO, schema.org profiles)."@en ; + rdfs:comment + "Works in conjunction with odrl:target. The promise targets a specific dataset (via odrl:target) and requires it to conform to a schema (via dprod:requiresConformanceTo). The referenced schema becomes a contractual commitment."@en ; + rdfs:label "requires conformance to" ; +. + + +############################# Service Level Properties ################ dprod:hasServiceLevelTarget - a owl:ObjectProperty ; - rdfs:label "has service level target"@en ; - skos:definition "Links a service level promise to its quantitative targets"@en ; - rdfs:domain dprod:ProviderServiceLevelPromise ; - rdfs:range dprod:ServiceLevelTarget ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ProviderServiceLevelPromise ; + rdfs:range dprod:ServiceLevelTarget ; + dct:description "Links a service level promise to its quantitative targets"@en ; + rdfs:label "has service level target" ; +. dprod:slaMetric - a owl:ObjectProperty ; - rdfs:label "SLA metric"@en ; - skos:definition "The type of service level metric being measured"@en ; - rdfs:domain dprod:ServiceLevelTarget ; - rdfs:range dprod:SLAMetric ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range dprod:SLAMetric ; + dct:description "The type of service level metric being measured"@en ; + rdfs:label "SLA metric" ; +. dprod:targetValue - a owl:DatatypeProperty ; - rdfs:label "target value"@en ; - skos:definition "The numeric target value for this metric"@en ; - rdfs:domain dprod:ServiceLevelTarget ; - rdfs:range xsd:decimal ; - rdfs:isDefinedBy . + a rdf:Property, owl:DatatypeProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range xsd:decimal ; + dct:description "The numeric target value for this metric"@en ; + rdfs:label "target value" ; +. dprod:unit - a owl:DatatypeProperty ; - rdfs:label "unit"@en ; - skos:definition "Unit of measurement (percentage, milliseconds, requests/second, etc.)"@en ; - rdfs:domain dprod:ServiceLevelTarget ; - rdfs:range xsd:string ; - rdfs:isDefinedBy . + a rdf:Property, owl:DatatypeProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range xsd:string ; + dct:description "Unit of measurement (percentage, milliseconds, requests/second, etc.)"@en ; + rdfs:label "unit" ; +. dprod:measurementPeriod - a owl:ObjectProperty ; - rdfs:label "measurement period"@en ; - skos:definition "The time window over which the metric is measured"@en ; - rdfs:domain dprod:ServiceLevelTarget ; - rdfs:range time:TemporalEntity ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ServiceLevelTarget ; + rdfs:range time:TemporalEntity ; + dct:description "The time window over which the metric is measured"@en ; + rdfs:label "measurement period" ; +. -# ============================================================================== -# PROPERTIES - Support Channel Properties -# ============================================================================== +############################# Support Channel Properties ################ dprod:hasSupportChannel - a owl:ObjectProperty ; - rdfs:label "has support channel"@en ; - skos:definition "Links a support promise to available support channels"@en ; - rdfs:domain dprod:ProviderSupportPromise ; - rdfs:range dprod:SupportChannel ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ProviderSupportPromise ; + rdfs:range dprod:SupportChannel ; + dct:description "Links a support promise to available support channels"@en ; + rdfs:label "has support channel" ; +. dprod:channelType - a owl:ObjectProperty ; - rdfs:label "channel type"@en ; - skos:definition "The type of support channel (email, Slack, ticket system, etc.)"@en ; - rdfs:domain dprod:SupportChannel ; - rdfs:range dprod:SupportChannelType ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:SupportChannel ; + rdfs:range dprod:SupportChannelType ; + dct:description "The type of support channel (email, Slack, ticket system, etc.)"@en ; + rdfs:label "channel type" ; +. dprod:channelUrl - a owl:DatatypeProperty ; - rdfs:label "channel URL"@en ; - skos:definition "URL or address for accessing this support channel"@en ; - rdfs:domain dprod:SupportChannel ; - rdfs:range xsd:anyURI ; - rdfs:isDefinedBy . + a rdf:Property, owl:DatatypeProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:SupportChannel ; + rdfs:range xsd:anyURI ; + dct:description "URL or address for accessing this support channel"@en ; + rdfs:label "channel URL" ; +. dprod:responseTimeTarget - a owl:ObjectProperty ; - rdfs:label "response time target"@en ; - skos:definition "Target response time for this support channel"@en ; - rdfs:domain dprod:SupportChannel ; - rdfs:range time:Duration ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:SupportChannel ; + rdfs:range time:Duration ; + dct:description "Target response time for this support channel"@en ; + rdfs:label "response time target" ; +. dprod:supportScope - a owl:ObjectProperty ; - rdfs:label "support scope"@en ; - skos:definition "What this channel covers (issues, questions, announcements)"@en ; - rdfs:domain dprod:SupportChannel ; - rdfs:range dprod:SupportScope ; - rdfs:isDefinedBy . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:SupportChannel ; + rdfs:range dprod:SupportScope ; + dct:description "What this channel covers (issues, questions, announcements)"@en ; + rdfs:label "support scope" ; +. -# ============================================================================== -# PROPERTIES - Pricing -# ============================================================================== +############################# Pricing Properties ################ dprod:hasPricing - a owl:ObjectProperty ; - rdfs:label "has pricing"@en ; - skos:definition "Pricing terms for data access under this contract"@en ; - rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; - rdfs:range schema:PriceSpecification ; - rdfs:isDefinedBy ; - skos:note "Use schema:PriceSpecification subclasses for different pricing models (per-unit, subscription, tiered). Optional - typically only used for external marketplace scenarios."@en . + a rdf:Property, owl:ObjectProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain [ owl:unionOf ( dprod:DataOffer dprod:DataContract ) ] ; + rdfs:range schema:PriceSpecification ; + dct:description "Pricing terms for data access under this contract"@en ; + rdfs:comment "Use schema:PriceSpecification subclasses for different pricing models (per-unit, subscription, tiered). Optional - typically only used for external marketplace scenarios."@en ; + rdfs:label "has pricing" ; +. -# ============================================================================== -# PROPERTIES - Schedule Properties -# ============================================================================== +############################# Schedule Properties ################ dprod:icalRule - a owl:DatatypeProperty ; - rdfs:label "iCal rule"@en ; - skos:definition "iCalendar RRULE specification for recurring schedules"@en ; - rdfs:domain dprod:ICalSchedule ; - rdfs:range xsd:string ; - rdfs:isDefinedBy ; - skos:note "Standard RFC 5545 RRULE format, e.g., 'FREQ=DAILY;BYHOUR=6;BYMINUTE=0'"@en . + a rdf:Property, owl:DatatypeProperty ; + rdfs:isDefinedBy dprod: ; + rdfs:domain dprod:ICalSchedule ; + rdfs:range xsd:string ; + dct:description "iCalendar RRULE specification for recurring schedules"@en ; + rdfs:comment "Standard RFC 5545 RRULE format, e.g., 'FREQ=DAILY;BYHOUR=6;BYMINUTE=0'"@en ; + rdfs:label "iCal rule" ; +. -# ============================================================================== -# CONTRACT STATUS VOCABULARY -# ============================================================================== +############################# Contract Status Vocabulary ######################### dprod:ContractStatusScheme - a skos:ConceptScheme ; - rdfs:label "DPROD Contract Status"@en ; - skos:definition "Vocabulary for data contract and offer lifecycle status values"@en ; - skos:hasTopConcept - dprod:ContractStatusPending, - dprod:ContractStatusActive, - dprod:ContractStatusExpired, - dprod:ContractStatusCancelled ; - rdfs:isDefinedBy ; - skos:note "Status concepts apply to both DataOffer (Pending, Expired, Cancelled) and DataContract (Active, Expired, Cancelled)"@en . + a skos:ConceptScheme ; + dct:description "Vocabulary for data contract and offer lifecycle status values"@en ; + rdfs:comment "Status concepts apply to both DataOffer (Pending, Expired, Cancelled) and DataContract (Active, Expired, Cancelled)"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "DPROD contract status" ; + skos:hasTopConcept + dprod:ContractStatusPending, + dprod:ContractStatusActive, + dprod:ContractStatusExpired, + dprod:ContractStatusCancelled ; +. dprod:ContractStatus - a owl:Class ; - rdfs:label "Contract Status"@en ; - skos:definition "Status value for data contracts and offers"@en ; - rdfs:subClassOf skos:Concept ; - rdfs:isDefinedBy ; - skos:note "Subclass of skos:Concept providing specific typing for contract lifecycle status values"@en . + a owl:Class, rdfs:Class ; + dct:description "Status value for data contracts and offers"@en ; + rdfs:comment "Subclass of skos:Concept providing specific typing for contract lifecycle status values"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "contract status" ; + rdfs:subClassOf skos:Concept ; +. dprod:ContractStatusPending - a dprod:ContractStatus ; - rdfs:label "Pending"@en ; - skos:prefLabel "Pending"@en ; - skos:definition "Offer is published and available for review, but not yet accepted by any consumer."@en ; - skos:inScheme dprod:ContractStatusScheme ; - skos:topConceptOf dprod:ContractStatusScheme ; - rdfs:isDefinedBy ; - skos:note "Applies to DataOffer only. Provider commitments are proposed but not yet binding. Once accepted, status becomes Active."@en . + a dprod:ContractStatus ; + dct:description "Offer is published and available for review, but not yet accepted by any consumer."@en ; + rdfs:comment "Applies to DataOffer only. Provider commitments are proposed but not yet binding. Once accepted, status becomes Active."@en ; + skos:prefLabel "Pending"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "pending" ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; +. dprod:ContractStatusActive - a dprod:ContractStatus ; - rdfs:label "Active"@en ; - skos:prefLabel "Active"@en ; - skos:definition "Data contract is in operation"@en ; - skos:inScheme dprod:ContractStatusScheme ; - skos:topConceptOf dprod:ContractStatusScheme ; - rdfs:isDefinedBy ; - skos:note "Contract is in effect. Provider commitments are in operation."@en . + a dprod:ContractStatus ; + dct:description "Data contract is in operation"@en ; + rdfs:comment "Contract is in effect. Provider commitments are in operation."@en ; + skos:prefLabel "Active"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "active" ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; +. dprod:ContractStatusExpired - a dprod:ContractStatus ; - rdfs:label "Expired"@en ; - skos:prefLabel "Expired"@en ; - skos:definition "Contract or offer has reached its natural end date as specified in the effective period."@en ; - skos:inScheme dprod:ContractStatusScheme ; - skos:topConceptOf dprod:ContractStatusScheme ; - rdfs:isDefinedBy ; - skos:note "Contract reached its scheduled termination date. Provider commitments are no longer in effect. Distinct from cancellation (early termination)."@en . + a dprod:ContractStatus ; + dct:description "Contract or offer has reached its natural end date as specified in the effective period."@en ; + rdfs:comment "Contract reached its scheduled termination date. Provider commitments are no longer in effect. Distinct from cancellation (early termination)."@en ; + skos:prefLabel "Expired"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "expired" ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; +. dprod:ContractStatusCancelled - a dprod:ContractStatus ; - rdfs:label "Cancelled"@en ; - skos:prefLabel "Cancelled"@en ; - skos:definition "Data contract has been cancelled before its planned retirement"@en ; - skos:inScheme dprod:ContractStatusScheme ; - skos:topConceptOf dprod:ContractStatusScheme ; - rdfs:isDefinedBy ; - skos:note "Contract has been cancelled. Provider commitments are no longer valid."@en . + a dprod:ContractStatus ; + dct:description "Data contract has been cancelled before its planned retirement"@en ; + rdfs:comment "Contract has been cancelled. Provider commitments are no longer valid."@en ; + skos:prefLabel "Cancelled"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "cancelled" ; + skos:inScheme dprod:ContractStatusScheme ; + skos:topConceptOf dprod:ContractStatusScheme ; +. -# ============================================================================== -# SLA METRIC VOCABULARY -# ============================================================================== +############################# SLA Metric Vocabulary ######################### dprod:SLAMetricScheme - a skos:ConceptScheme ; - rdfs:label "DPROD SLA Metrics"@en ; - skos:definition "Vocabulary for service level agreement metrics"@en ; - skos:hasTopConcept dprod:Availability, dprod:Latency, dprod:Throughput, - dprod:ErrorRate, dprod:ResponseTime ; - rdfs:isDefinedBy . + a skos:ConceptScheme ; + dct:description "Vocabulary for service level agreement metrics"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "DPROD SLA metrics" ; + skos:hasTopConcept dprod:Availability, dprod:Latency, dprod:Throughput, + dprod:ErrorRate, dprod:ResponseTime ; +. dprod:SLAMetric - a owl:Class ; - rdfs:label "SLA Metric"@en ; - skos:definition "Type of service level metric"@en ; - rdfs:subClassOf skos:Concept ; - rdfs:isDefinedBy . + a owl:Class, rdfs:Class ; + dct:description "Type of service level metric"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "SLA metric" ; + rdfs:subClassOf skos:Concept ; +. dprod:Availability - a dprod:SLAMetric ; - rdfs:label "Availability"@en ; - skos:prefLabel "Availability"@en ; - skos:definition "Percentage of time the service is operational and accessible"@en ; - skos:inScheme dprod:SLAMetricScheme ; - skos:topConceptOf dprod:SLAMetricScheme ; - rdfs:isDefinedBy . + a dprod:SLAMetric ; + dct:description "Percentage of time the service is operational and accessible"@en ; + skos:prefLabel "Availability"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "availability" ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; +. dprod:Latency - a dprod:SLAMetric ; - rdfs:label "Latency"@en ; - skos:prefLabel "Latency"@en ; - skos:definition "Time delay in data delivery or processing"@en ; - skos:inScheme dprod:SLAMetricScheme ; - skos:topConceptOf dprod:SLAMetricScheme ; - rdfs:isDefinedBy . + a dprod:SLAMetric ; + dct:description "Time delay in data delivery or processing"@en ; + skos:prefLabel "Latency"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "latency" ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; +. dprod:Throughput - a dprod:SLAMetric ; - rdfs:label "Throughput"@en ; - skos:prefLabel "Throughput"@en ; - skos:definition "Volume of data processed per unit time"@en ; - skos:inScheme dprod:SLAMetricScheme ; - skos:topConceptOf dprod:SLAMetricScheme ; - rdfs:isDefinedBy . + a dprod:SLAMetric ; + dct:description "Volume of data processed per unit time"@en ; + skos:prefLabel "Throughput"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "throughput" ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; +. dprod:ErrorRate - a dprod:SLAMetric ; - rdfs:label "Error Rate"@en ; - skos:prefLabel "Error Rate"@en ; - skos:definition "Percentage of failed requests or invalid records"@en ; - skos:inScheme dprod:SLAMetricScheme ; - skos:topConceptOf dprod:SLAMetricScheme ; - rdfs:isDefinedBy . + a dprod:SLAMetric ; + dct:description "Percentage of failed requests or invalid records"@en ; + skos:prefLabel "Error Rate"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "error rate" ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; +. dprod:ResponseTime - a dprod:SLAMetric ; - rdfs:label "Response Time"@en ; - skos:prefLabel "Response Time"@en ; - skos:definition "Time to respond to a request (may specify percentile: p50, p95, p99)"@en ; - skos:inScheme dprod:SLAMetricScheme ; - skos:topConceptOf dprod:SLAMetricScheme ; - rdfs:isDefinedBy . + a dprod:SLAMetric ; + dct:description "Time to respond to a request (may specify percentile: p50, p95, p99)"@en ; + skos:prefLabel "Response Time"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "response time" ; + skos:inScheme dprod:SLAMetricScheme ; + skos:topConceptOf dprod:SLAMetricScheme ; +. -# ============================================================================== -# SUPPORT CHANNEL TYPE VOCABULARY -# ============================================================================== +############################# Support Channel Type Vocabulary ######################### dprod:SupportChannelTypeScheme - a skos:ConceptScheme ; - rdfs:label "Support Channel Types"@en ; - skos:definition "Types of support channels available for data contracts"@en ; - skos:hasTopConcept dprod:EmailSupport, dprod:SlackSupport, dprod:TeamsSupport, - dprod:TicketSupport, dprod:DocumentationSupport ; - rdfs:isDefinedBy . + a skos:ConceptScheme ; + dct:description "Types of support channels available for data contracts"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "support channel types" ; + skos:hasTopConcept dprod:EmailSupport, dprod:SlackSupport, dprod:TeamsSupport, + dprod:TicketSupport, dprod:DocumentationSupport ; +. dprod:SupportChannelType - a owl:Class ; - rdfs:label "Support Channel Type"@en ; - skos:definition "Type of support channel"@en ; - rdfs:subClassOf skos:Concept ; - rdfs:isDefinedBy . + a owl:Class, rdfs:Class ; + dct:description "Type of support channel"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "support channel type" ; + rdfs:subClassOf skos:Concept ; +. dprod:EmailSupport - a dprod:SupportChannelType ; - rdfs:label "Email"@en ; - skos:prefLabel "Email"@en ; - skos:definition "Support via email"@en ; - skos:inScheme dprod:SupportChannelTypeScheme ; - skos:topConceptOf dprod:SupportChannelTypeScheme ; - rdfs:isDefinedBy . + a dprod:SupportChannelType ; + dct:description "Support via email"@en ; + skos:prefLabel "Email"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "email" ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; +. dprod:SlackSupport - a dprod:SupportChannelType ; - rdfs:label "Slack"@en ; - skos:prefLabel "Slack"@en ; - skos:definition "Support via Slack channel"@en ; - skos:inScheme dprod:SupportChannelTypeScheme ; - skos:topConceptOf dprod:SupportChannelTypeScheme ; - rdfs:isDefinedBy . + a dprod:SupportChannelType ; + dct:description "Support via Slack channel"@en ; + skos:prefLabel "Slack"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "Slack" ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; +. dprod:TeamsSupport - a dprod:SupportChannelType ; - rdfs:label "Microsoft Teams"@en ; - skos:prefLabel "Microsoft Teams"@en ; - skos:definition "Support via Microsoft Teams channel"@en ; - skos:inScheme dprod:SupportChannelTypeScheme ; - skos:topConceptOf dprod:SupportChannelTypeScheme ; - rdfs:isDefinedBy . + a dprod:SupportChannelType ; + dct:description "Support via Microsoft Teams channel"@en ; + skos:prefLabel "Microsoft Teams"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "Microsoft Teams" ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; +. dprod:TicketSupport - a dprod:SupportChannelType ; - rdfs:label "Ticket System"@en ; - skos:prefLabel "Ticket System"@en ; - skos:definition "Support via ticketing system (JIRA, ServiceNow, etc.)"@en ; - skos:inScheme dprod:SupportChannelTypeScheme ; - skos:topConceptOf dprod:SupportChannelTypeScheme ; - rdfs:isDefinedBy . + a dprod:SupportChannelType ; + dct:description "Support via ticketing system (JIRA, ServiceNow, etc.)"@en ; + skos:prefLabel "Ticket System"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "ticket system" ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; +. dprod:DocumentationSupport - a dprod:SupportChannelType ; - rdfs:label "Documentation"@en ; - skos:prefLabel "Documentation"@en ; - skos:definition "Self-service support via documentation and FAQs"@en ; - skos:inScheme dprod:SupportChannelTypeScheme ; - skos:topConceptOf dprod:SupportChannelTypeScheme ; - rdfs:isDefinedBy . + a dprod:SupportChannelType ; + dct:description "Self-service support via documentation and FAQs"@en ; + skos:prefLabel "Documentation"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "documentation" ; + skos:inScheme dprod:SupportChannelTypeScheme ; + skos:topConceptOf dprod:SupportChannelTypeScheme ; +. -# ============================================================================== -# SUPPORT SCOPE VOCABULARY -# ============================================================================== +############################# Support Scope Vocabulary ######################### dprod:SupportScopeScheme - a skos:ConceptScheme ; - rdfs:label "Support Scopes"@en ; - skos:definition "Scopes of support coverage for channels"@en ; - skos:hasTopConcept dprod:InteractiveSupport, dprod:IssueResolution, - dprod:Announcements, dprod:SelfService ; - rdfs:isDefinedBy . + a skos:ConceptScheme ; + dct:description "Scopes of support coverage for channels"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "support scopes" ; + skos:hasTopConcept dprod:InteractiveSupport, dprod:IssueResolution, + dprod:Announcements, dprod:SelfService ; +. dprod:SupportScope - a owl:Class ; - rdfs:label "Support Scope"@en ; - skos:definition "Scope of support coverage"@en ; - rdfs:subClassOf skos:Concept ; - rdfs:isDefinedBy . + a owl:Class, rdfs:Class ; + dct:description "Scope of support coverage"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "support scope" ; + rdfs:subClassOf skos:Concept ; +. dprod:InteractiveSupport - a dprod:SupportScope ; - rdfs:label "Interactive"@en ; - skos:prefLabel "Interactive"@en ; - skos:definition "Real-time Q&A and troubleshooting support"@en ; - skos:inScheme dprod:SupportScopeScheme ; - skos:topConceptOf dprod:SupportScopeScheme ; - rdfs:isDefinedBy . + a dprod:SupportScope ; + dct:description "Real-time Q&A and troubleshooting support"@en ; + skos:prefLabel "Interactive"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "interactive" ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; +. dprod:IssueResolution - a dprod:SupportScope ; - rdfs:label "Issue Resolution"@en ; - skos:prefLabel "Issue Resolution"@en ; - skos:definition "Bug reports and incident handling"@en ; - skos:inScheme dprod:SupportScopeScheme ; - skos:topConceptOf dprod:SupportScopeScheme ; - rdfs:isDefinedBy . + a dprod:SupportScope ; + dct:description "Bug reports and incident handling"@en ; + skos:prefLabel "Issue Resolution"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "issue resolution" ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; +. dprod:Announcements - a dprod:SupportScope ; - rdfs:label "Announcements"@en ; - skos:prefLabel "Announcements"@en ; - skos:definition "One-way notifications about changes and updates"@en ; - skos:inScheme dprod:SupportScopeScheme ; - skos:topConceptOf dprod:SupportScopeScheme ; - rdfs:isDefinedBy . + a dprod:SupportScope ; + dct:description "One-way notifications about changes and updates"@en ; + skos:prefLabel "Announcements"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "announcements" ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; +. dprod:SelfService - a dprod:SupportScope ; - rdfs:label "Self Service"@en ; - skos:prefLabel "Self Service"@en ; - skos:definition "Documentation and FAQ resources"@en ; - skos:inScheme dprod:SupportScopeScheme ; - skos:topConceptOf dprod:SupportScopeScheme ; - rdfs:isDefinedBy . + a dprod:SupportScope ; + dct:description "Documentation and FAQ resources"@en ; + skos:prefLabel "Self Service"@en ; + rdfs:isDefinedBy dprod: ; + rdfs:label "self service" ; + skos:inScheme dprod:SupportScopeScheme ; + skos:topConceptOf dprod:SupportScopeScheme ; +. -# ============================================================================== -# ODRL PROFILE DECLARATION -# ============================================================================== +############################# ODRL Profile Declaration ######################### - a odrl:Profile, skos:ConceptScheme ; - rdfs:label "DPROD ODRL Profile"@en ; - skos:definition "ODRL profile for DPROD Data Contract Ontology defining custom actions and promise-based commitments"@en ; - dct:description "Extends ODRL Core with promise-based patterns for bilateral data contracts, distinguishing provider obligations from consumer restrictions"@en ; - dct:creator "EKGF DPROD Working Group" ; - dct:created "2025-10-30"^^xsd:date ; - dct:modified "2025-12-18"^^xsd:date ; - owl:versionInfo "9.0.0" ; - rdfs:seeAlso ; - skos:note """This profile defines: + a odrl:Profile, skos:ConceptScheme ; + dct:description "Extends ODRL Core with promise-based patterns for bilateral data contracts, distinguishing provider obligations from consumer restrictions"@en ; + rdfs:comment "ODRL profile for DPROD Data Contract Ontology defining custom actions and promise-based commitments"@en ; + dct:creator "EKGF DPROD Working Group" ; + dct:created "2025-10-30"^^xsd:date ; + dct:modified "2025-12-18"^^xsd:date ; + owl:versionInfo "9.0.0" ; + rdfs:label "DPROD ODRL profile" ; + rdfs:seeAlso ; + rdfs:comment """This profile defines: Core Classes: - dprod:DataOffer: Provider's standing offer (extends odrl:Offer) - not binding until accepted @@ -1088,17 +1107,16 @@ dprod:SelfService - dprod:restrictPurpose (includedIn odrl:use): Restrict to declared purpose Policies using this profile should declare: odrl:profile - """@en . + """@en ; +. -# ============================================================================== -# USAGE PATTERNS DOCUMENTATION -# ============================================================================== +############################# Usage Patterns Documentation ######################### - a skos:ConceptScheme ; - rdfs:label "DPROD Usage Patterns"@en ; - skos:note """ + a skos:ConceptScheme ; + rdfs:label "DPROD usage patterns" ; + rdfs:comment """ DPROD v8.0 Usage for Data Providers: 1. Create DataOffer with odrl:assigner (provider's standing offer) @@ -1129,4 +1147,5 @@ dprod:SelfService Example: Adding new compliance requirements to existing agreement Suitable for both internal organizational data sharing and external data marketplaces. - """@en . + """@en ; +. From 8793e238f28cf438bd0348d8d85ee2ebcd97d6d4 Mon Sep 17 00:00:00 2001 From: tonys Date: Thu, 29 Jan 2026 17:11:39 +0000 Subject: [PATCH 03/10] Match the DPROD shapes formatting. --- .gitignore | 1 + dprod-contracts/dprod-contracts-shapes.ttl | 32 ++++++++++++++++------ 2 files changed, 25 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index e30e616..bb19a89 100644 --- a/.gitignore +++ b/.gitignore @@ -62,3 +62,4 @@ code/bin/ code/lib/ code/include */__pycache__ +/.idea/LNKD.tech Editor.xml diff --git a/dprod-contracts/dprod-contracts-shapes.ttl b/dprod-contracts/dprod-contracts-shapes.ttl index d973a85..3523c4d 100644 --- a/dprod-contracts/dprod-contracts-shapes.ttl +++ b/dprod-contracts/dprod-contracts-shapes.ttl @@ -1,3 +1,8 @@ +# baseURI: https://ekgf.github.io/dprod/contracts/shapes +# imports: https://ekgf.github.io/dprod/contracts +# prefix: dprod + +@base . @prefix dprod: . @prefix dcat: . @prefix dct: . @@ -8,14 +13,15 @@ @prefix schema: . @prefix skos: . @prefix rdfs: . +@prefix owl: . +@prefix rdf: . @prefix prov: . -################################################################ -# SHACL Shapes for DPROD Data Contract Ontology -################################################################ -# Validation rules that complement the class definitions in drrod.ttl + +############################# SHACL Shapes for DPROD Data Contract Ontology ######################### +# Validation rules that complement the class definitions in dprod-contracts.ttl # These shapes replace OWL restrictions for better platform compatibility -################################################################ + # Shape for DataOffer dprod:DataOfferShape @@ -75,6 +81,8 @@ dprod:DataContractShape . +############################# Promise Shapes ######################### + # Shape for Promise (base) dprod:PromiseShape a sh:NodeShape ; @@ -265,6 +273,9 @@ dprod:ProviderTerminationNoticePromiseShape ] ; . + +############################# Schedule Shapes ######################### + # Shape for Schedule (union class validation) dprod:ScheduleShape a sh:NodeShape ; @@ -307,6 +318,9 @@ dprod:ICalScheduleShape ] ; . + +############################# Temporal Shapes ######################### + # Shape for hasEffectivePeriod time intervals dprod:EffectivePeriodShape a sh:NodeShape ; @@ -363,6 +377,9 @@ dprod:NoticePeriodShape ] ; . + +############################# Status & Linkage Shapes ######################### + # Shape for contract status values dprod:ContractStatusConceptShape a sh:NodeShape ; @@ -404,9 +421,8 @@ dprod:DataProductShape ] ; . -################################################################ -# v9.0 SHACL Shapes - Service Level and Support Promises -################################################################ + +############################# Service Level & Support Shapes ######################### # Shape for ProviderServiceLevelPromise dprod:ProviderServiceLevelPromiseShape From dc2b0c92a7b92797d97a0ab8d657c71398f550b4 Mon Sep 17 00:00:00 2001 From: tonys Date: Thu, 26 Feb 2026 19:11:06 +0000 Subject: [PATCH 04/10] Move to the new version of Data contracts by Mattias Autrata (it is much clearner!) --- dprod-contracts/DATA-CONTRACTS.md | 742 ---------- dprod-contracts/README.md | 187 ++- .../docs/ODCS-DPROD-Comparison-Report.md | 586 -------- dprod-contracts/docs/contracts-guide.md | 579 ++++++++ dprod-contracts/docs/display.html | 126 -- dprod-contracts/docs/formal-semantics.md | 1127 ++++++++++++++ dprod-contracts/docs/overview.md | 206 +++ dprod-contracts/docs/policy-writers-guide.md | 551 +++++++ dprod-contracts/docs/specification.md | 516 +++++++ dprod-contracts/docs/term-mapping.md | 497 +++++++ dprod-contracts/dprod-contract-examples.ttl | 632 -------- dprod-contracts/dprod-contracts-prof.ttl | 68 + dprod-contracts/dprod-contracts-shapes.ttl | 794 +++++----- dprod-contracts/dprod-contracts.ttl | 1314 +++-------------- dprod-contracts/dprod-due.ttl | 804 ++++++++++ dprod-contracts/examples/baseline.ttl | 659 +++++++++ dprod-contracts/examples/data-contract.ttl | 219 +++ dprod-contracts/examples/data-use-policy.ttl | 194 +++ dprod-contracts/requirements.txt | 4 - 19 files changed, 6192 insertions(+), 3613 deletions(-) delete mode 100644 dprod-contracts/DATA-CONTRACTS.md delete mode 100644 dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md create mode 100644 dprod-contracts/docs/contracts-guide.md delete mode 100644 dprod-contracts/docs/display.html create mode 100644 dprod-contracts/docs/formal-semantics.md create mode 100644 dprod-contracts/docs/overview.md create mode 100644 dprod-contracts/docs/policy-writers-guide.md create mode 100644 dprod-contracts/docs/specification.md create mode 100644 dprod-contracts/docs/term-mapping.md delete mode 100644 dprod-contracts/dprod-contract-examples.ttl create mode 100644 dprod-contracts/dprod-contracts-prof.ttl create mode 100644 dprod-contracts/dprod-due.ttl create mode 100644 dprod-contracts/examples/baseline.ttl create mode 100644 dprod-contracts/examples/data-contract.ttl create mode 100644 dprod-contracts/examples/data-use-policy.ttl delete mode 100644 dprod-contracts/requirements.txt diff --git a/dprod-contracts/DATA-CONTRACTS.md b/dprod-contracts/DATA-CONTRACTS.md deleted file mode 100644 index d9b7232..0000000 --- a/dprod-contracts/DATA-CONTRACTS.md +++ /dev/null @@ -1,742 +0,0 @@ -# DPROD Data Contracts Extension - -## Overview - -**Data Contracts** are formal agreements between data providers and consumers that specify commitments about data quality, delivery schedules, schemas, and usage restrictions. The DPROD Data Contracts extension builds on [ODRL (Open Digital Rights Language)](https://www.w3.org/TR/odrl-model/) to create machine-readable, enforceable agreements for internal organizational data sharing. - -### What is a Data Contract? - -A data contract is a bilateral agreement between two parties: -- **Provider** (assigner): The team or system that produces and delivers the data -- **Consumer** (assignee): The team or system that receives and uses the data - -Unlike legal contracts, data contracts focus on **technical commitments**: -- When will data be delivered? (timeliness) -- What schema must the data conform to? (structure) -- How will changes be communicated? (governance) -- How may the data be used? (restrictions) - -### Why Data Contracts? - -Data contracts address common organizational challenges: - -| Problem | Contract Solution | -|---------|------------------| -| "The daily report is late again" | **Timeliness Promise** with delivery schedule | -| "They changed the schema and broke our pipeline" | **Schema Promise** with SHACL validation + change notification | -| "We can't use this data for compliance reasons" | **Usage Restrictions** with consumer promises | -| "No one told us they were deprecating this API" | **Termination Notice Promise** with notice period | - -### How DPROD Implements Data Contracts - -DPROD extends ODRL with: - -1. **Promise-based commitments**: Providers make promises to deliver quality data; consumers make promises about appropriate use -2. **Temporal modeling**: Schedules (iCalendar RRULE), effective periods, notice periods -3. **Schema integration**: Links to SHACL shapes, OWL ontologies, or industry standards -4. **Lifecycle management**: Contract status (Pending → Active → Expired/Cancelled) -5. **Provenance tracking**: How contracts derive from offers and evolve over time - ---- - -## Quick Start: Core Pattern - -### Simple Example (JSON-LD) - -Here's a minimal data contract showing the essential pattern: - -```json -{ - "@context": { - "dprod": "https://ekgf.github.io/dprod/", - "dcat": "http://www.w3.org/ns/dcat#", - "odrl": "http://www.w3.org/ns/odrl/2/", - "xsd": "http://www.w3.org/2001/XMLSchema#" - }, - "@id": "https://example.com/contract/daily-sales", - "@type": "dprod:DataContract", - - "odrl:assigner": { - "@id": "https://example.com/team/sales-ops", - "rdfs:label": "Sales Operations Team" - }, - - "odrl:assignee": { - "@id": "https://example.com/team/finance", - "rdfs:label": "Finance Team" - }, - - "odrl:target": { - "@id": "https://example.com/dataset/daily-sales", - "@type": "dcat:Dataset", - "rdfs:label": "Daily Sales Dataset" - }, - - "dprod:providerPromise": { - "@type": "dprod:ProviderTimelinessPromise", - "rdfs:label": "Deliver by 8am daily", - "odrl:action": "dprod:fulfill", - "dprod:hasSchedule": { - "@type": "dprod:ICalSchedule", - "dprod:icalRule": "FREQ=DAILY;BYHOUR=8;BYMINUTE=0" - } - }, - - "dprod:contractStatus": "dprod:ContractStatusActive", - - "dprod:hasEffectivePeriod": { - "@type": "time:Interval", - "time:hasBeginning": "2025-01-01T00:00:00Z", - "time:hasEnd": "2025-12-31T23:59:59Z" - } -} -``` - -**What this says:** -- Sales Ops promises to deliver the daily sales dataset to Finance -- Delivery happens daily at 8am UTC -- The contract is active for calendar year 2025 - ---- - -## Architecture Overview - -### Class Hierarchy (Mermaid Diagram) - -```mermaid -graph TD - A[odrl:Policy] --> B[odrl:Offer] - A --> C[odrl:Agreement] - B --> D[dprod:DataOffer] - C --> E[dprod:DataContract] - C --> F[dprod:DataSubscription] - - G[odrl:Rule] --> H[dprod:Promise] - H --> I[dprod:ProviderPromise] - H --> J[dprod:ConsumerPromise] - - I --> K[dprod:ProviderTimelinessPromise] - I --> L[dprod:ProviderSchemaPromise] - I --> M[dprod:ProviderTerminationNoticePromise] - - N[dcat:Dataset] -.target.-> E - N -.target.-> D - O[dcat:DataService] -.target.-> E - P[dprod:DataProduct] -.target.-> E - - E -.providerPromise.-> I - E -.consumerPromise.-> J - - style D fill:#e1f5ff - style E fill:#ffe1e1 - style F fill:#ffe1e1 - style H fill:#fff4e1 - style I fill:#e1ffe1 - style J fill:#ffe1f5 -``` - -### Key Relationships - -| From | Property | To | Meaning | -|------|----------|-----|---------| -| DataContract | `odrl:assigner` | Party | Who provides the data | -| DataContract | `odrl:assignee` | Party | Who consumes the data | -| DataContract | `odrl:target` | Dataset/DataService | What data is governed | -| DataContract | `dprod:providerPromise` | ProviderPromise | Provider's commitments | -| DataContract | `dprod:consumerPromise` | ConsumerPromise | Consumer's obligations | -| ProviderSchemaPromise | `dprod:requiresConformanceTo` | SHACL Shape | Required schema | -| ProviderTimelinessPromise | `dprod:hasSchedule` | Schedule | Delivery schedule | - ---- - -## Main Classes - -### dprod:DataContract - -**Definition**: A bilateral agreement between a data provider and consumer specifying mutual commitments. - -**Extends**: `odrl:Agreement`, `prov:Entity` - -**Required Properties**: -- `odrl:assigner` — The provider party -- `odrl:assignee` — The consumer party -- `odrl:target` — The governed data asset (Dataset, DataService, or DataProduct) - -**Common Properties**: -- `dprod:providerPromise` — Provider commitments (1 or more) -- `dprod:consumerPromise` — Consumer obligations (0 or more) -- `dprod:hasEffectivePeriod` — When the contract is valid (`time:Interval`) -- `dprod:contractStatus` — Lifecycle status (Pending, Active, Expired, Cancelled) -- `dcat:version` — Contract version number -- `dprod:supersedes` — Previous contract this replaces -- `dprod:amends` — Base contract this extends - -**Example**: -```json -{ - "@id": "https://example.com/contract/ml-training-2025", - "@type": "dprod:DataContract", - "odrl:assigner": "https://example.com/team/data-eng", - "odrl:assignee": "https://example.com/team/ml-ops", - "odrl:target": "https://example.com/dataset/clickstream", - "dprod:providerPromise": [ - { "@id": "#schema-freeze" }, - { "@id": "#daily-8am" } - ], - "dprod:contractStatus": "dprod:ContractStatusActive" -} -``` - ---- - -### dprod:ProviderPromise - -**Definition**: A commitment made by the data provider about quality, timeliness, or governance. - -**Extends**: `odrl:Rule` (disjoint with Duty, Permission, Prohibition) - -**Required Properties**: -- `odrl:action` — Must be `dprod:fulfill` - -**Subclasses**: -- `dprod:ProviderTimelinessPromise` — Delivery schedule commitments -- `dprod:ProviderSchemaPromise` — Schema conformance guarantees -- `dprod:ProviderTerminationNoticePromise` — Advance notice of changes/termination - ---- - -### dprod:ProviderTimelinessPromise - -**Definition**: Promise about when data will be delivered or updated. - -**Key Property**: -- `dprod:hasSchedule` — Schedule object (iCalendar RRULE or schema.org Schedule) - -**Example**: -```json -{ - "@type": "dprod:ProviderTimelinessPromise", - "rdfs:label": "Hourly refresh", - "odrl:action": "dprod:fulfill", - "dprod:hasSchedule": { - "@type": "dprod:ICalSchedule", - "dprod:icalRule": "FREQ=HOURLY;INTERVAL=1" - } -} -``` - -**Common Schedules**: -- Daily at 6am: `FREQ=DAILY;BYHOUR=6;BYMINUTE=0` -- Every 5 minutes: `FREQ=MINUTELY;INTERVAL=5` -- Weekly on Monday: `FREQ=WEEKLY;BYDAY=MO` -- Quarterly: Use `schema:Schedule` with `schema:repeatFrequency "P3M"` - ---- - -### dprod:ProviderSchemaPromise - -**Definition**: Promise that data will conform to a specified schema or standard. - -**Key Properties**: -- `odrl:target` — The specific dataset this promise applies to -- `dprod:requiresConformanceTo` — The schema (SHACL shape, OWL ontology, or industry standard) - -**Example**: -```json -{ - "@type": "dprod:ProviderSchemaPromise", - "rdfs:label": "Customer schema stability", - "odrl:action": "dprod:fulfill", - "odrl:target": "https://example.com/dataset/customers", - "dprod:requiresConformanceTo": { - "@id": "https://example.com/shape/customer-v2", - "@type": ["sh:NodeShape", "dct:Standard"], - "rdfs:label": "Customer Schema V2" - } -} -``` - -This pattern enables **automated validation**: the provider can validate data against the SHACL shape before delivery, ensuring contract compliance. - ---- - -### dprod:ProviderTerminationNoticePromise - -**Definition**: Promise to give advance notice before terminating a contract or introducing breaking changes. - -**Key Properties**: -- `odrl:action` — Must be `dprod:issueNotice` -- `dprod:noticePeriod` — Required lead time (`time:Interval`) - -**Example**: -```json -{ - "@type": "dprod:ProviderTerminationNoticePromise", - "rdfs:label": "90-day change notice", - "odrl:action": "dprod:issueNotice", - "dprod:noticePeriod": { - "@type": "time:Interval", - "rdfs:comment": "90 days advance notice required" - } -} -``` - -This prevents surprise breaking changes that disrupt downstream consumers. - ---- - -### dprod:ConsumerPromise - -**Definition**: A commitment made by the data consumer about how they will use the data. - -**Required Properties**: -- `odrl:action` — Typically `dprod:performCompliantUse` - -**Example**: -```json -{ - "@type": "dprod:ConsumerPromise", - "rdfs:label": "Marketing use only", - "rdfs:comment": "Data may only be used for campaign targeting, not credit decisions", - "odrl:action": "dprod:performCompliantUse" -} -``` - -Common consumer promises: -- **Usage restrictions**: "Only for fraud detection, not marketing" -- **Retention policies**: "Delete after 90 days per GDPR" -- **Rate limits**: "Max 1000 API calls per minute" -- **Access controls**: "Provide read-only access to external auditors" - ---- - -## Usage Patterns - -### Pattern 1: Schema Validation Guarantee - -**Scenario**: Data Engineering promises ML team that clickstream data will conform to a stable schema for the entire year. - -**Contract** (simplified): -```json -{ - "@context": { - "dprod": "https://ekgf.github.io/dprod/", - "dcat": "http://www.w3.org/ns/dcat#", - "odrl": "http://www.w3.org/ns/odrl/2/", - "sh": "http://www.w3.org/ns/shacl#", - "xsd": "http://www.w3.org/2001/XMLSchema#" - }, - - "@id": "https://example.com/contract/ml-clickstream-2025", - "@type": "dprod:DataContract", - - "rdfs:label": "ML Training Clickstream Contract 2025", - - "odrl:assigner": { - "@id": "https://example.com/team/data-eng", - "rdfs:label": "Data Engineering" - }, - - "odrl:assignee": { - "@id": "https://example.com/team/ml-ops", - "rdfs:label": "ML Operations" - }, - - "odrl:target": { - "@id": "https://example.com/dataset/clickstream-training", - "@type": "dcat:Dataset", - "dcat:title": "Clickstream Training Dataset" - }, - - "dprod:providerPromise": { - "@type": "dprod:ProviderSchemaPromise", - "rdfs:label": "Schema Freeze for 2025", - "rdfs:comment": "No breaking changes to ClickStreamV2 schema during 2025", - "odrl:action": "dprod:fulfill", - "odrl:target": "https://example.com/dataset/clickstream-training", - - "dprod:requiresConformanceTo": { - "@id": "https://example.com/shape/clickstream-v2", - "@type": ["sh:NodeShape", "dct:Standard"], - "rdfs:label": "ClickStream V2 Schema", - - "sh:property": [ - { - "sh:path": "ex:userId", - "sh:datatype": "xsd:string", - "sh:minCount": 1, - "sh:pattern": "^[a-f0-9]{64}$", - "rdfs:comment": "SHA-256 hashed user ID" - }, - { - "sh:path": "ex:timestamp", - "sh:datatype": "xsd:dateTime", - "sh:minCount": 1 - }, - { - "sh:path": "ex:eventType", - "sh:datatype": "xsd:string", - "sh:in": ["page_view", "click", "purchase"] - } - ] - } - }, - - "dprod:hasEffectivePeriod": { - "@type": "time:Interval", - "time:hasBeginning": "2025-01-01T00:00:00Z", - "time:hasEnd": "2025-12-31T23:59:59Z" - }, - - "dprod:contractStatus": "dprod:ContractStatusActive" -} -``` - -**Value**: ML team can train models knowing the schema won't change mid-year and break production pipelines. - ---- - -### Pattern 2: Timeliness with Daily Schedule - -**Scenario**: Finance promises Marketing that customer segmentation data will refresh daily at 6am UTC. - -**Contract** (simplified): -```json -{ - "@context": { - "dprod": "https://ekgf.github.io/dprod/", - "dcat": "http://www.w3.org/ns/dcat#", - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - - "@id": "https://example.com/contract/customer-segments-2025", - "@type": "dprod:DataContract", - - "rdfs:label": "Customer Segmentation Contract", - - "odrl:assigner": "https://example.com/dept/finance", - "odrl:assignee": "https://example.com/dept/marketing", - "odrl:target": "https://example.com/dataset/customer-segments", - - "dprod:providerPromise": [ - { - "@type": "dprod:ProviderTimelinessPromise", - "rdfs:label": "Daily 6am refresh", - "odrl:action": "dprod:fulfill", - "dprod:hasSchedule": { - "@type": "dprod:ICalSchedule", - "dprod:icalRule": "FREQ=DAILY;BYHOUR=6;BYMINUTE=0", - "rdfs:comment": "Daily at 06:00 UTC" - } - }, - { - "@type": "dprod:ProviderSchemaPromise", - "rdfs:label": "Segment schema guarantee", - "odrl:action": "dprod:fulfill", - "odrl:target": "https://example.com/dataset/customer-segments", - "dprod:requiresConformanceTo": "https://example.com/shape/customer-segment" - } - ], - - "dprod:consumerPromise": { - "@type": "dprod:ConsumerPromise", - "rdfs:label": "Campaign use only", - "rdfs:comment": "Marketing may only use for campaign targeting, not credit decisions", - "odrl:action": "dprod:performCompliantUse" - } -} -``` - -**Value**: Marketing knows exactly when data arrives for their 9am campaign launches. Finance commits to not changing the schema without notice. - ---- - -### Pattern 3: Privacy-Safe Data with Validation - -**Scenario**: Product Analytics promises Personalization team that user behavior data will be privacy-safe (PII removed, GDPR-compliant). - -**Contract** (simplified): -```json -{ - "@context": { - "dprod": "https://ekgf.github.io/dprod/", - "dcat": "http://www.w3.org/ns/dcat#", - "odrl": "http://www.w3.org/ns/odrl/2/", - "sh": "http://www.w3.org/ns/shacl#" - }, - - "@id": "https://example.com/contract/user-behavior-personalization", - "@type": "dprod:DataContract", - - "odrl:assigner": "https://example.com/team/product-analytics", - "odrl:assignee": "https://example.com/team/personalization", - "odrl:target": "https://example.com/dataset/user-events", - - "dprod:providerPromise": { - "@type": "dprod:ProviderSchemaPromise", - "rdfs:label": "Privacy-safe events", - "rdfs:comment": "All PII removed before delivery - safe for ML use", - "odrl:action": "dprod:fulfill", - "odrl:target": "https://example.com/dataset/user-events", - - "dprod:requiresConformanceTo": { - "@id": "https://example.com/shape/privacy-compliant-events", - "@type": ["sh:NodeShape", "dct:Standard"], - "rdfs:label": "Privacy-Compliant Events Shape", - "rdfs:comment": "Enforces PII removal via SHACL validation", - - "sh:property": [ - { - "sh:path": "ex:userId", - "sh:pattern": "^[a-f0-9]{64}$", - "rdfs:comment": "Must be SHA-256 hash, not plaintext" - }, - { - "sh:path": "ex:eventType", - "sh:in": ["page_view", "product_click", "add_to_cart"] - } - ], - - "sh:not": [ - { "sh:path": "ex:email" }, - { "sh:path": "ex:ipAddress" }, - { "sh:path": "ex:phoneNumber" } - ], - - "rdfs:comment": "Validation fails if email, IP, or phone present - acts as privacy firewall" - } - }, - - "dprod:consumerPromise": { - "@type": "dprod:ConsumerPromise", - "rdfs:label": "GDPR deletion compliance", - "rdfs:comment": "Honor deletion requests within 30 days, retrain models without deleted users", - "odrl:action": "dprod:performCompliantUse" - } -} -``` - -**Value**: The SHACL shape acts as a **privacy firewall** — data fails validation if PII leaks through. Personalization team can use the data confidently for ML. - ---- - -### Pattern 4: Change Notification with Termination Notice - -**Scenario**: Sales Ops provides API access to Customer Success team with a 90-day notice requirement before breaking changes. - -**Contract** (simplified): -```json -{ - "@context": { - "dprod": "https://ekgf.github.io/dprod/", - "dcat": "http://www.w3.org/ns/dcat#", - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - - "@id": "https://example.com/contract/customer-account-api", - "@type": "dprod:DataContract", - - "odrl:assigner": "https://example.com/team/sales-ops", - "odrl:assignee": "https://example.com/team/customer-success", - - "odrl:target": { - "@id": "https://example.com/service/customer-account-api", - "@type": "dcat:DataService", - "dcat:title": "Customer Account API v2" - }, - - "dprod:providerPromise": [ - { - "@type": "dprod:ProviderSchemaPromise", - "rdfs:label": "API v2 stability", - "rdfs:comment": "API follows semantic versioning - v2 stays stable", - "odrl:action": "dprod:fulfill", - "odrl:target": "https://example.com/service/customer-account-api", - "dprod:requiresConformanceTo": "https://example.com/spec/customer-api-v2-openapi" - }, - { - "@type": "dprod:ProviderTerminationNoticePromise", - "rdfs:label": "90-day deprecation notice", - "odrl:action": "dprod:issueNotice", - "dprod:noticePeriod": { - "@type": "time:Interval", - "rdfs:comment": "Minimum 90 days notice before v2 deprecation or breaking changes" - } - } - ], - - "dprod:consumerPromise": { - "@type": "dprod:ConsumerPromise", - "rdfs:label": "Rate limit compliance", - "rdfs:comment": "Max 1000 requests/minute - enforced by API gateway", - "odrl:action": "dprod:performCompliantUse" - } -} -``` - -**Value**: Customer Success team can build integrations confidently knowing they'll get 90 days to migrate before v3 or breaking changes. - ---- - -## Contract Lifecycle - -Contracts progress through statuses: - -```mermaid -stateDiagram-v2 - [*] --> Pending: Contract created - Pending --> Active: Effective period starts - Active --> Expired: Natural end date reached - Active --> Cancelled: Early termination - Expired --> [*] - Cancelled --> [*] -``` - -**Status Vocabulary** (`dprod:ContractStatus`): -- `dprod:ContractStatusPending` — Negotiation or awaiting effective date -- `dprod:ContractStatusActive` — Currently in force -- `dprod:ContractStatusExpired` — Reached natural end date -- `dprod:ContractStatusCancelled` — Terminated before planned end - -**Contract Versioning**: -- `dprod:supersedes` — This contract replaces a previous version (old becomes Expired/Cancelled) -- `dprod:amends` — This contract extends/modifies a base contract (both remain Active) - -**Example** (renewal): -```json -{ - "@id": "https://example.com/contract/2025-renewal", - "@type": "dprod:DataContract", - "dprod:supersedes": "https://example.com/contract/2024", - "dcat:version": "2.0", - "rdfs:comment": "2025 renewal with updated SLAs" -} -``` - ---- - -## Integration with DPROD Data Products - -Data contracts naturally integrate with DPROD Data Products: - -```json -{ - "@id": "https://example.com/product/customer-360", - "@type": "dprod:DataProduct", - "dcat:title": "Customer 360 Data Product", - - "odrl:hasPolicy": { - "@id": "https://example.com/offer/customer-360-standard", - "@type": "dprod:DataOffer", - "rdfs:comment": "Standing offer - anyone can request access" - }, - - "dprod:dataContract": [ - { - "@id": "https://example.com/contract/finance-customer-360", - "@type": "dprod:DataContract", - "odrl:assignee": "https://example.com/dept/finance", - "rdfs:comment": "Finance's active contract" - }, - { - "@id": "https://example.com/contract/marketing-customer-360", - "@type": "dprod:DataContract", - "odrl:assignee": "https://example.com/dept/marketing", - "rdfs:comment": "Marketing's active contract" - } - ] -} -``` - -This allows a single data product to have: -- **One offer** (the standard terms available to anyone) -- **Many contracts** (executed agreements with specific consumers) - ---- - -## Best Practices - -### 1. Start Simple -Begin with minimal contracts containing just timeliness or schema promises. Add complexity as needed. - -### 2. Make Schemas Machine-Readable -Use SHACL shapes (not just comments) so providers can validate data before delivery: -```bash -# Validate data before delivery -pyshacl --shacl customer-shape.ttl --data-file daily-export.ttl -``` - -### 3. Use iCalendar for Schedules -[RFC 5545 RRULE](https://icalendar.org/iCalendar-RFC-5545/3-3-10-recurrence-rule.html) is widely supported: -- Libraries: Python `dateutil.rrule`, JavaScript `rrule.js` -- Clear semantics: `FREQ=DAILY;BYHOUR=8` is unambiguous - -### 4. Version Your Contracts -Use `dcat:version` and provenance properties (`supersedes`, `amends`) to track evolution. - -### 5. Automate Monitoring -Build monitors that check: -- Is data arriving on schedule? (timeliness promise) -- Does data validate against the shape? (schema promise) -- Are notice periods being honored? (termination promise) - -### 6. Link to Governance -Embed contracts in your data catalog (DCAT) and governance tools. Contracts are *metadata* that should be discoverable. - ---- - -## Namespace Declarations - -For JSON-LD contexts: - -```json -{ - "@context": { - "dprod": "https://ekgf.github.io/dprod/", - "dcat": "http://www.w3.org/ns/dcat#", - "dct": "http://purl.org/dc/terms/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "prov": "http://www.w3.org/ns/prov#", - "skos": "http://www.w3.org/2004/02/skos/core#", - "rdfs": "http://www.w3.org/2000/01/rdf-schema#", - "xsd": "http://www.w3.org/2001/XMLSchema#", - "time": "http://www.w3.org/2006/time#", - "sh": "http://www.w3.org/ns/shacl#", - "schema": "http://schema.org/" - } -} -``` - -For Turtle: -```turtle -@prefix dprod: . -@prefix dcat: . -@prefix dct: . -@prefix odrl: . -@prefix prov: . -@prefix time: . -@prefix sh: . -``` - ---- - -## Further Reading - -- **ODRL Information Model**: https://www.w3.org/TR/odrl-model/ -- **DCAT3 Specification**: https://www.w3.org/TR/vocab-dcat-3/ -- **SHACL**: https://www.w3.org/TR/shacl/ -- **PROV-O**: https://www.w3.org/TR/prov-o/ -- **iCalendar RRULE**: https://icalendar.org/iCalendar-RFC-5545/3-3-10-recurrence-rule.html -- **DPROD Specification**: https://ekgf.github.io/dprod/ - ---- - -## Appendix: Complete Example - -See [`dprod-contract-examples.ttl`](./dprod-contract-examples.ttl) for comprehensive Turtle examples demonstrating: -- Finance → Marketing customer segmentation contract -- Data Engineering → ML Ops training data contract -- Sales → Customer Success API access contract -- Accounting → Audit quarterly SOX compliance contract -- Product Analytics → Personalization privacy-safe events contract -- Contract lifecycle and versioning patterns diff --git a/dprod-contracts/README.md b/dprod-contracts/README.md index 0adaa0d..4794638 100644 --- a/dprod-contracts/README.md +++ b/dprod-contracts/README.md @@ -1,49 +1,172 @@ -# DPROD Data Contracts Ontology +# DPROD Data Contracts: Deterministic Policy Language for Data Governance -A semantic web ontology for formalizing **Data Contracts** - bilateral agreements between data providers and consumers using W3C standards. +**An ODRL 2.2 profile with deterministic evaluation semantics for data governance.** -## Overview +--- -DPROD Data Contracts models: -- **DataContract** - Binding agreement between provider and consumer -- **DataOffer** - Provider's proposal for data access -- **Provider Promises** - Timeliness, schema conformance, change notification -- **Consumer Promises** - Usage restrictions, retention policies +## What This Is -Built on: RDF, OWL, SHACL, ODRL, DCAT +DPROD Contracts is a proper ODRL 2.2 profile. It uses ODRL terms for all standard constructs (Permission, Duty, Prohibition, Agreement, etc.) and only adds extensions where ODRL 2.2 leaves behavior undefined: -## Files +1. **Explicit lifecycle**: Pending -> Active -> Fulfilled/Violated (unified for duties and contracts) +2. **Bilateral agreements**: Both assigner and assignee may have duties +3. **Deterministic evaluation**: Total functions, no undefined states +4. **Formal verification target**: Amenable to Dafny, Why3, Coq +5. **Structured operand resolution**: `resolutionPath` from canonical roots (agent, asset, context) +6. **Recurring duties**: `recurrence` via RFC 5545 RRULE for scheduled obligations -| File | Purpose | -|------|---------| -| `dprod-contracts.ttl` | Core ontology (classes, properties) | -| `dprod-contracts-shapes.ttl` | SHACL validation shapes | -| `dprod-contract-examples.ttl` | Example instances | +DPROD Contracts is **specification-first**. The semantics document defines what any conformant implementation must do. Every DPROD policy is a valid ODRL 2.2 policy. + +--- ## Quick Start -```bash -# Install dependencies -python -m venv .venv -source .venv/bin/activate -pip install -r requirements.txt +See [examples/](examples/) for complete working policies: + +- [data-contract.ttl](examples/data-contract.ttl) -- DataContract, Subscription, bilateral duties +- [data-use-policy.ttl](examples/data-use-policy.ttl) -- Role-based access, purpose constraints + +--- + +## What DPROD Contracts Adds to ODRL 2.2 + +| Extension | ODRL 2.2 | What DPROD Adds | +|-----------|----------|-----------------| +| Duty lifecycle | Undefined | Pending -> Active -> Fulfilled/Violated | +| Bilateral duties | Unilateral (assignee only) | Assigner duties + assignee duties | +| Conflict resolution | Configurable | Fixed: Prohibition > Permission | +| Evaluation order | Undefined | Deterministic left-to-right | +| Operand resolution | Implicit | Explicit `resolutionPath` from canonical roots | +| Recurring duties | -- | `recurrence` via RFC 5545 RRULE with per-instance `deadline` | +| Contract types | -- | `DataContract` (subclass of Offer), `Subscription` (subclass of Agreement) | + +**Note**: DPROD Contracts is an ODRL profile, not a parallel vocabulary. Standard ODRL processors can parse DPROD policies; DPROD-aware processors additionally enforce lifecycle, bilateral duties, and deterministic evaluation. + +--- + +## Design Principles + +### 1. Specification Precedes Implementation + +The [formal semantics](docs/formal-semantics.md) is the normative reference. + +### 2. Total Functions + +Every evaluation terminates with a defined result: + +``` +Eval : Request x PolicySet x State -> Decision x DutySet +``` + +### 3. Bilateral Agreements + +Agreements return duties for **both** parties: + +``` +Result = { + decision: Permit | Deny | NotApplicable, + assignerDuties: Set, // Provider obligations (SLAs) + assigneeDuties: Set, // Consumer obligations + violations: Set +} +``` + +### 4. Unified Lifecycle State + +Duties and contracts share four states: + +``` + condition true +Pending ──────────────> Active + │ │ + action done │ │ deadline passed + ▼ ▼ + Fulfilled Violated +``` + +An `odrl:Duty` progresses through `dprod:State` values. A `dprod:DataContract` shares the same state machine. + +### 5. Structured Operand Resolution + +Operands resolve via `resolutionPath` -- dot-separated paths from canonical roots: + +``` +agent.role, agent.organization, agent.costCenter +asset.classification, asset.market, asset.isBenchmark +context.purpose, context.environment, context.legalBasis +``` + +--- -# Validate examples against shapes -pyshacl -s dprod-contracts-shapes.ttl -df turtle dprod-contract-examples.ttl +## Repository Structure + +``` +dprod-contracts/ +├── dprod-contracts.ttl # Core ontology (ODRL profile extension) +├── dprod-contracts-shapes.ttl # SHACL validation shapes +├── dprod-contracts-prof.ttl # DXPROF profile declaration +├── dprod-due.ttl # Data use vocabulary (all operands + actions) +├── examples/ +│ ├── data-contract.ttl # Complete contract example (with recurrence) +│ ├── data-use-policy.ttl # Access control example +│ └── baseline.ttl # Comprehensive test data (8 contracts, 2 subscriptions) +└── docs/ + ├── overview.md # What is DPROD Contracts? (start here) + ├── specification.md # Technical vocabulary reference + ├── term-mapping.md # Business term -> property mapping + DCON migration + ├── formal-semantics.md # Formal semantics (normative) + ├── contracts-guide.md # Data contract authoring guide + └── policy-writers-guide.md # Data use policy authoring guide ``` -## Documentation +--- + +## Historical Context: DCON + +DPROD Contracts builds on the earlier DCON work. DCON's promise hierarchy dissolves into standard `odrl:Duty` patterns with DUE actions (`deliver`, `notify`, `conformTo`, `report`). Recurring obligations use `dprod:recurrence` (RFC 5545 RRULE) instead of DCON's scheduling constraints. + +| DCON | DPROD Contracts | Status | +|------|-----------------|--------| +| `dcon:DataContract` | `dprod:DataContract` | Absorbed into core | +| `dcon:DataContractSubscription` | `dprod:Subscription` | Absorbed into core | +| `dcon:Promise` hierarchy | `odrl:Duty` + DUE actions | Dissolved | +| `dcon:promisedDeliveryTime` | `dprod:recurrence` + `dprod:deadline` | Scheduling + window | + +See [term-mapping.md](docs/term-mapping.md) for complete DCON -> DPROD property mapping, and [contracts-guide.md](docs/contracts-guide.md) for the contracts authoring guide. + +> **Promise terminology.** If you prefer DCON-style "promise" naming (ProviderPromise, QualityPromise, etc.), this can be reintroduced as syntactic sugar. A promise is a Duty where `dprod:subject` equals the policy's `odrl:assigner`. Two options: **(1)** LinkML authoring sugar -- a `promise` class that expands to a standard Duty, no ontology change; **(2)** OWL thin alias -- `dprod:Promise rdfs:subClassOf odrl:Duty` with a SHACL constraint, making promises queryable in SPARQL. + +--- + +## Namespaces + +| Prefix | Namespace | Role | +|--------|-----------|------| +| `odrl:` | `http://www.w3.org/ns/odrl/2/` | Primary -- all standard constructs | +| `dprod:` | `https://ekgf.github.io/dprod/contracts/` | Extensions only (State, deadline, recurrence, DataContract, Subscription, resolutionPath, hierarchy) | +| `dprod-due:` | `https://ekgf.github.io/dprod/due/` | Data use vocabulary (operands, domain-specific actions, concept values); ODRL Common Vocabulary actions used directly | + +--- + +## Conformance + +An implementation conforms to DPROD Contracts if: + +1. It accepts policies that validate against `dprod-contracts-shapes.ttl` +2. It uses `odrl:Permission`, `odrl:Duty`, `odrl:Prohibition`, `odrl:Agreement` for standard constructs +3. Its evaluation function produces identical results for identical inputs +4. All functions are total (no undefined behavior) +5. State transitions match the operational semantics +6. Agreement evaluation returns duties for both assigner and assignee -- [DATA-CONTRACTS.md](DATA-CONTRACTS.md) - Full specification and usage patterns -- [CLAUDE.md](CLAUDE.md) - Design philosophy and development guide -- [AGENTS.md](AGENTS.md) - Contribution guidelines +--- -## Related +## References -- [DPROD (Data Product Ontology)](https://ekgf.github.io/dprod/) - Parent ontology -- [DCAT](https://www.w3.org/TR/vocab-dcat-3/) - W3C Data Catalog Vocabulary -- [ODRL](https://www.w3.org/TR/odrl-model/) - Open Digital Rights Language +- [ODRL 2.2 Information Model](https://www.w3.org/TR/odrl-model/) +- [W3C Market Data Profile](https://www.w3.org/2021/md-odrl-profile/v1/) +- [W3C ODRL Profile Best Practices](https://www.w3.org/community/reports/odrl/CG-FINAL-profile-bp-20240808.html) -## License +--- -MIT +**Version**: 0.7 | **Date**: 2026-02-04 diff --git a/dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md b/dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md deleted file mode 100644 index 6ae533d..0000000 --- a/dprod-contracts/docs/ODCS-DPROD-Comparison-Report.md +++ /dev/null @@ -1,586 +0,0 @@ -# DPROD Data Contract Ontology: Comparison Report - -**Comparison with Open Data Contract Standard (ODCS)** - -| | | -|---|---| -| **Date** | 2025-12-19 | -| **Version** | DPROD v9.0 vs ODCS v3.1 | -| **Purpose** | Design validation through use case comparison | -| **Verdict** | **Feature Complete** - Full parity with ODCS | - ---- - -## 1. Executive Summary - -This report evaluates the DPROD Data Contract Ontology by comparing its capabilities against the Open Data Contract Standard (ODCS), a widely-adopted YAML-based specification maintained by the Linux Foundation's Bitol project. - -### Key Findings - -| Category | DPROD Assessment | -|----------|------------------| -| **Rights & Obligations** | Superior - ODRL-based policy language | -| **Versioning & Provenance** | Superior - Rich semantic relationships | -| **Schema Handling** | Equivalent - Different approach (reference vs inline) | -| **SLA Metrics** | Equivalent - Quantitative targets with measurement periods | -| **Data Quality Rules** | Simplified - Promise-based with descriptive text | -| **Support Channels** | Superior - Structured channels with response times | -| **Infrastructure** | Acceptable - Appropriately abstracted | -| **Pricing** | Equivalent - schema.org integration | - -### Recommendation - -The DPROD ontology is **feature complete** for both internal organizational data sharing and external marketplace scenarios. - ---- - -## 2. Standards Compared - -### DPROD Data Contract Ontology -- **Format**: RDF/Turtle (Semantic Web) -- **Foundation**: W3C vocabularies (ODRL, DCAT, PROV, TIME, ORG) -- **Approach**: Promise-based bilateral agreements -- **Validation**: SHACL shapes -- **Target Use**: Internal and external data sharing with quantitative SLAs - -### Open Data Contract Standard (ODCS) -- **Format**: YAML -- **Foundation**: Custom schema with JSON Schema validation -- **Approach**: Document-centric specification -- **Validation**: JSON Schema -- **Target Use**: General data contracts (internal and external) - ---- - -## 3. Use Case Analysis - -### 3.1 Schema Definition & Validation - -#### ODCS Approach -```yaml -schema: - - name: customers - physicalName: CUSTOMERS - properties: - - name: customer_id - logicalType: string - physicalType: VARCHAR(50) - required: true - primaryKey: true - classification: internal -``` - -#### DPROD Approach -```turtle -ex:contract dprod:providerPromise [ - a dprod:ProviderSchemaPromise ; - odrl:action dprod:maintainSchema ; - odrl:target ex:customerDataset ; - dprod:requiresConformanceTo ex:CustomerSchema -] . - -ex:CustomerSchema a dct:Standard, sh:NodeShape ; - sh:targetClass ex:Customer ; - sh:property [ sh:path ex:customerId ; sh:minCount 1 ] . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Schema location | External reference | Inline | -| Reusability | High (shared schemas) | Low (duplicated per contract) | -| Validation | SHACL (W3C standard) | JSON Schema | -| Human readability | Lower (RDF syntax) | Higher (YAML) | - -**Verdict**: Different approaches with trade-offs. DPROD's separation of concerns is appropriate for an ontology. - ---- - -### 3.2 Service Level Agreements - -#### ODCS Approach -```yaml -slaProperties: - - property: latency - value: 99.5 - unit: percentage - driver: operational - - property: generalAvailability - value: 99.99 - unit: percentage - - property: endOfSupport - value: 2026-12-31 -``` - -#### DPROD Approach -```turtle -ex:contract dprod:providerPromise [ - a dprod:ProviderServiceLevelPromise ; - rdfs:label "99.9% Availability SLA" ; - dct:description "Provider guarantees 99.9% uptime measured monthly." ; - odrl:action dprod:meetServiceLevel ; - dprod:hasServiceLevelTarget [ - a dprod:ServiceLevelTarget ; - dprod:slaMetric dprod:Availability ; - dprod:targetValue 99.9 ; - dprod:unit "percentage" ; - dprod:measurementPeriod [ - a time:Interval ; - time:hasDuration "P1M"^^xsd:duration - ] - ] , - [ - a dprod:ServiceLevelTarget ; - dprod:slaMetric dprod:ResponseTime ; - dprod:targetValue 500 ; - dprod:unit "milliseconds" ; - dct:description "p95 response time" - ] -] . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Delivery schedules | Strong (iCal support) | Basic | -| Availability metrics | Structured | Structured | -| Latency targets | Structured | Structured | -| Measurement units | Supported | Supported | -| Measurement periods | Supported (time:Interval) | Not supported | -| Metric vocabulary | 5 standard metrics | Custom per contract | - -**Verdict**: Full parity with additional support for measurement periods. - ---- - -### 3.3 Data Quality Rules - -#### ODCS Approach -```yaml -quality: - - dimension: completeness - type: library - metric: nullValues - mustBeLessThan: 5 - unit: percentage - - dimension: accuracy - type: sql - query: "SELECT COUNT(*) FROM ${table} WHERE invalid = true" -``` - -#### DPROD Approach -```turtle -ex:contract dprod:providerPromise [ - a dprod:ProviderPromise ; - rdfs:label "Data Quality Guarantee" ; - dct:description "Provider commits to: (1) 99.5% completeness, (2) <0.1% duplicates, (3) 99.9% validity." ; - odrl:action dprod:maintainQuality -] . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Quality commitment | Promise with descriptive text | Structured metrics | -| Threshold values | Human-readable in description | Machine-readable | -| Validation queries | Not supported (external concern) | SQL templates | -| Complexity | Low | High | -| Flexibility | High (any commitment expressible) | Constrained by schema | - -**Verdict**: DPROD takes a simpler approach - quality commitments are expressed as promises with descriptive text. For machine-readable quality metrics, use W3C DQV directly on datasets. SQL validation queries are appropriately an external concern. - ---- - -### 3.4 Consumer Rights & Restrictions - -#### ODCS Approach -```yaml -roles: - - role: data-consumer - access: read-only - firstLevelApprovers: data-steward -``` - -#### DPROD Approach -```turtle -ex:contract dprod:consumerPromise - [ a dprod:ConsumerPromise ; - rdfs:label "Query Access Only" ; - odrl:action dprod:query ] , - [ a dprod:ConsumerPromise ; - rdfs:label "No External Redistribution" ; - odrl:action dprod:restrictPurpose ] , - [ a dprod:ConsumerPromise ; - rdfs:label "Delete on Contract Expiry" ; - odrl:action dprod:deleteOnExpiry ] . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Access types | Rich vocabulary (query, download, stream) | Basic (read/write) | -| Usage restrictions | Detailed (restrictPurpose, deleteOnExpiry) | Limited | -| Transformation rights | Supported (deriveInsights, aggregate, anonymize) | Not addressed | -| Distribution rights | Supported (redistribute, shareInternally) | Not addressed | - -**Verdict**: DPROD is **significantly stronger** for rights management. - ---- - -### 3.5 Contract Lifecycle & Versioning - -#### ODCS Approach -```yaml -status: active -version: 1.2.0 -``` - -#### DPROD Approach -```turtle -ex:contract2025 a dprod:DataContract ; - dprod:contractStatus dprod:ContractStatusActive ; - dcat:version "2.0" ; - dprod:supersedes ex:contract2024 . - -ex:amendment a dprod:DataContract ; - dprod:amends ex:contract2025 ; - rdfs:comment "Adds GDPR compliance requirements" . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Status vocabulary | Rich (Pending, Active, Expired, Cancelled) | Basic | -| Version numbering | Supported | Supported | -| Replacement tracking | `supersedes` relationship | Not supported | -| Amendment tracking | `amends` relationship | Not supported | -| Provenance | PROV-O integration | Not supported | -| Offer→Contract flow | Two-stage model | Single document | - -**Verdict**: DPROD is **superior** for lifecycle management. - ---- - -### 3.6 Support Channels - -#### ODCS Approach -```yaml -support: - - channel: slack - url: https://company.slack.com/data-support - - channel: email - email: data-support@company.com -``` - -#### DPROD Approach -```turtle -ex:contract dprod:providerPromise [ - a dprod:ProviderSupportPromise ; - rdfs:label "Technical Support Commitment" ; - odrl:action dprod:provideSupport ; - dprod:hasSupportChannel [ - a dprod:SupportChannel ; - dprod:channelType dprod:SlackSupport ; - dprod:channelUrl "https://company.slack.com/data-support"^^xsd:anyURI ; - dprod:supportScope dprod:InteractiveSupport ; - dprod:responseTimeTarget [ time:hours 4 ] - ] , - [ - a dprod:SupportChannel ; - dprod:channelType dprod:TicketSupport ; - dprod:channelUrl "https://jira.company.com/servicedesk"^^xsd:anyURI ; - dprod:supportScope dprod:IssueResolution ; - dprod:responseTimeTarget [ time:hours 24 ] - ] -] . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Channel types | 5 standard types (Email, Slack, Teams, Ticket, Docs) | Custom | -| Channel URL | Supported | Supported | -| Response time targets | Supported (time:Duration) | Not supported | -| Support scope | 4 scope types (Interactive, Issues, Announcements, Self-service) | Not supported | - -**Verdict**: DPROD is **superior** for support channel specification. - ---- - -### 3.7 Pricing (Marketplace Scenarios) - -#### ODCS Approach -```yaml -pricing: - - model: usage - unit: GB - price: 0.05 - currency: USD -``` - -#### DPROD Approach -```turtle -ex:offer a dprod:DataOffer ; - dprod:hasPricing [ - a schema:UnitPriceSpecification ; - schema:price 0.05 ; - schema:priceCurrency "USD" ; - schema:unitText "per GB" ; - schema:referenceQuantity [ - a schema:QuantitativeValue ; - schema:value 1 ; - schema:unitCode "E34" # GB in UN/CEFACT - ] - ] . - -# Alternative: Subscription pricing -ex:offer2 dprod:hasPricing [ - a schema:PriceSpecification ; - schema:price 500 ; - schema:priceCurrency "USD" ; - schema:billingDuration "P1M"^^xsd:duration -] . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Usage-based pricing | Supported (schema:UnitPriceSpecification) | Supported | -| Subscription pricing | Supported (billingDuration) | Limited | -| Currency | Supported | Supported | -| Quantity units | Supported (UN/CEFACT codes) | Custom | -| Standards alignment | schema.org | Custom | - -**Verdict**: Full parity with superior standards alignment via schema.org. - ---- - -### 3.8 Infrastructure Configuration - -#### ODCS Approach -```yaml -servers: - - server: production-warehouse - type: snowflake - account: acme.us-east-1 - database: ANALYTICS - schema: CUSTOMERS -``` - -#### DPROD Approach -```turtle -ex:dataset dcat:distribution [ - a dcat:Distribution ; - dcat:accessURL ; - dcat:mediaType "application/json" -] . -``` - -#### Assessment - -| Aspect | DPROD | ODCS | -|--------|-------|------| -| Abstraction level | High (URL-based) | Low (server-specific) | -| Platform details | Not included | Detailed (Snowflake, BigQuery, etc.) | -| Standards alignment | DCAT (W3C) | Custom | - -**Verdict**: DPROD's abstraction is **appropriate**. Operational infrastructure details belong in deployment configurations, not contracts. - ---- - -## 4. Strengths Summary - -### DPROD Advantages Over ODCS - -1. **Semantic Interoperability** - - Built on W3C standards (ODRL, DCAT, PROV, TIME, ORG) - - Integrates with knowledge graphs and data catalogs - - Machine-interpretable relationships - -2. **Rights Management** - - 15+ consumer action types vs ODCS's basic role model - - Clear separation of permissions vs obligations - - Extensible action hierarchy - -3. **Contract Evolution** - - `supersedes` captures complete replacement - - `amends` captures addendums - - `prov:wasDerivedFrom` tracks acceptance from offers - - Full audit trail capability - -4. **Promise-Based Model** - - Clear bilateral structure (provider promises, consumer promises) - - Cleaner than ODRL's duty/permission/prohibition split - - Self-documenting through action semantics - -5. **Validation Framework** - - SHACL shapes provide executable constraints - - Separable from ontology for flexibility - - Industry-standard tooling support - -6. **Quantitative Commitments** - - Service level targets with measurement periods - - Support channels with response time targets - - Pricing via schema.org integration - ---- - -## 5. Design Scope - -### In Scope - -| Capability | Implementation | -|------------|----------------| -| **Quantitative SLAs** | `ProviderServiceLevelPromise` + `ServiceLevelTarget` | -| **Quality Commitments** | `ProviderPromise` + `maintainQuality` action | -| **Support Channels** | `ProviderSupportPromise` + `SupportChannel` | -| **Pricing** | `hasPricing` + `schema:PriceSpecification` | -| **Rights Management** | 15+ consumer action types | -| **Contract Lifecycle** | `supersedes`, `amends`, status vocabulary | - -### Intentionally Out of Scope - -| Item | Rationale | -|------|-----------| -| **Data Classification** | Dataset metadata - attach to `dcat:Dataset` | -| **Lineage** | Dataset metadata - use PROV-O patterns on datasets | -| **SQL Validation Queries** | Operational concern - belongs in monitoring/quality tools | -| **Infrastructure Details** | Deployment configuration - use DCAT distributions | - -### Design Principles - -1. **Separation of Concerns**: Contracts declare intent; monitoring systems track compliance -2. **Standards Alignment**: W3C vocabularies over custom schemas -3. **Extensibility**: RDF allows adding properties without breaking existing contracts - ---- - -## 6. Validation Verdict - -### Design Decision Review - -| Decision | Validation | -|----------|------------| -| ODRL as foundation | **Correct** - Provides extensible policy framework | -| Promise-based model | **Correct** - Cleaner than duty/permission split | -| DCAT integration | **Correct** - Leverages catalog infrastructure | -| Schema by reference | **Correct** - Enables reuse, separates concerns | -| PROV versioning | **Correct** - Captures real-world contract evolution | -| SHACL validation | **Correct** - Platform-compatible, executable | -| Simplified quality | **Correct** - Promise-based; use DQV on datasets | -| schema.org for pricing | **Correct** - Wide adoption, rich model | - -### Final Assessment - -**The DPROD Data Contract Ontology is feature complete.** - -- Full parity with ODCS for quantitative metrics -- Superior for rights management and lifecycle tracking -- W3C standards alignment throughout -- Suitable for both internal and marketplace scenarios - ---- - -## 7. References - -- [Open Data Contract Standard (ODCS)](https://github.com/bitol-io/open-data-contract-standard) -- [ODCS Documentation](https://bitol-io.github.io/open-data-contract-standard/v3.0.2/) -- [W3C ODRL](https://www.w3.org/TR/odrl-model/) -- [W3C DCAT](https://www.w3.org/TR/vocab-dcat-2/) -- [W3C Data Quality Vocabulary](https://www.w3.org/TR/vocab-dqv/) -- [W3C PROV-O](https://www.w3.org/TR/prov-o/) -- [Schema.org PriceSpecification](https://schema.org/PriceSpecification) - ---- - -## Appendix A: DPROD Action Vocabulary - -### Provider Obligation Actions -| Action | Description | -|--------|-------------| -| `dprod:deliverOnSchedule` | Deliver per agreed schedule | -| `dprod:maintainSchema` | Maintain schema conformance | -| `dprod:maintainQuality` | Maintain data quality standards | -| `dprod:meetServiceLevel` | Meet quantitative SLA targets | -| `dprod:notifyChange` | Notify of breaking changes | -| `dprod:notifyTermination` | Provide termination notice | -| `dprod:provideSupport` | Provide technical support | - -### Consumer Obligation Actions -| Action | Description | -|--------|-------------| -| `dprod:complyWithTerms` | Comply with usage terms | -| `dprod:deleteOnExpiry` | Delete data when contract expires | -| `dprod:reportUsage` | Report usage metrics | -| `dprod:provideAttribution` | Attribute data source | -| `dprod:restrictPurpose` | Restrict to declared purpose | - -### Consumer Access Actions -| Action | Description | -|--------|-------------| -| `dprod:query` | Execute queries against data service | -| `dprod:download` | Download data locally | -| `dprod:stream` | Receive real-time feeds | -| `dprod:access` | General data access | - -### Consumer Transformation Actions -| Action | Description | -|--------|-------------| -| `dprod:deriveInsights` | Create analytics/insights | -| `dprod:aggregate` | Combine with other data | -| `dprod:anonymize` | Remove PII before use | -| `dprod:enrich` | Add value/annotations | - -### Consumer Distribution Actions -| Action | Description | -|--------|-------------| -| `dprod:shareInternally` | Share within organization | -| `dprod:republish` | Publish derived datasets | -| `dprod:redistribute` | Share with third parties | - ---- - -## Appendix B: DPROD Vocabularies - -### SLA Metrics (`dprod:SLAMetricScheme`) -| Metric | Description | -|--------|-------------| -| `dprod:Availability` | Percentage of time service is operational | -| `dprod:Latency` | Time delay in data delivery | -| `dprod:Throughput` | Volume processed per unit time | -| `dprod:ErrorRate` | Percentage of failed requests | -| `dprod:ResponseTime` | Time to respond (p50, p95, p99) | - -### Support Channel Types (`dprod:SupportChannelTypeScheme`) -| Type | Description | -|------|-------------| -| `dprod:EmailSupport` | Email-based support | -| `dprod:SlackSupport` | Slack channel | -| `dprod:TeamsSupport` | Microsoft Teams | -| `dprod:TicketSupport` | Ticket/issue system | -| `dprod:DocumentationSupport` | Self-service docs | - -### Support Scopes (`dprod:SupportScopeScheme`) -| Scope | Description | -|-------|-------------| -| `dprod:InteractiveSupport` | Real-time Q&A | -| `dprod:IssueResolution` | Bug/incident handling | -| `dprod:Announcements` | One-way notifications | -| `dprod:SelfService` | Documentation/FAQ | - ---- - -## Appendix C: Critical Files - -| File | Purpose | Triples | -|------|---------|---------| -| `dprod-contracts.ttl` | Main ontology definitions | 764 | -| `dprod-contracts-shapes.ttl` | SHACL validation shapes | 339 | -| `dprod-contract-examples.ttl` | Usage examples (8 examples) | 380 | diff --git a/dprod-contracts/docs/contracts-guide.md b/dprod-contracts/docs/contracts-guide.md new file mode 100644 index 0000000..0674ede --- /dev/null +++ b/dprod-contracts/docs/contracts-guide.md @@ -0,0 +1,579 @@ +# DPROD Contracts Guide + +A guide for data platform teams using DPROD for data contracts and subscriptions. + +--- + +## Overview + +DPROD models internal data sharing agreements as ODRL 2.2 policies. A **DataContract** is an offer from a data provider. A **Subscription** is an activated contract binding provider and consumer. + +``` +DataContract (Offer) Subscription (Agreement) ++--------------------------+ +--------------------------+ +| Provider duties | | Provider duties | +| Consumer rights | | Consumer rights | +| Prohibitions | | Consumer duties | +| Recurrence rules | | Prohibitions | ++--------------------------+ | State tracking | + accept +--------------------------+ + --------> +``` + +--- + +## Key Concepts + +### DataContract (Offer) + +A `dprod:DataContract` is a subclass of `odrl:Offer`. It specifies: + +- **Provider** (`odrl:assigner`): the data team providing data +- **Target** (`odrl:target`): the data asset(s) covered -- inherited by rules unless overridden +- **Provider duties** (`odrl:obligation` with `dprod:subject` = provider): SLAs like delivery, notification, schema conformance +- **Consumer permissions** (`odrl:permission`): what consumers can do with the data +- **Consumer duties** (`odrl:obligation` without subject in Offer): obligations consumers accept upon subscribing +- **Prohibitions** (`odrl:prohibition`): what consumers cannot do + +### Subscription (Agreement) + +A `dprod:Subscription` is a subclass of `odrl:Agreement`. It adds: + +- **Consumer** (`odrl:assignee`): the subscribing team +- **Effective/expiration dates**: contract period +- **State tracking**: lifecycle state on duties and the subscription itself + +### Provider Duties + +Provider duties use DUE actions: + +| Action | Description | Example | +|--------|-------------|---------| +| `dprod-due:deliver` | Deliver data to consumers | Daily market data delivery | +| `dprod-due:notify` | Send notifications | Schema change notification | +| `dprod-due:conformTo` | Maintain conformance to a standard | Schema/quality SLA | + +### Consumer Duties + +| Action | Description | Example | +|--------|-------------|---------| +| `dprod-due:report` | Submit usage reports | Monthly usage reporting | + +### Permissions + +Standard ODRL actions apply: + +| Action | Description | +|--------|-------------| +| `odrl:display` | Display data | +| `dprod-due:nonDisplay` | Non-display (algorithmic) use | +| `odrl:derive` | Create derived products | +| `odrl:read` | Read data | + +--- + +## Step-by-Step Cookbook + +Create your first DataContract in five steps. + +### Step 1: Declare the Contract + +Every contract starts with a type, profile declaration, and provider identity. + +```turtle +@prefix odrl: . +@prefix dprod: . +@prefix dprod-due: . +@prefix xsd: . + +ex:contract a dprod:DataContract ; + odrl:profile , + ; + odrl:assigner ex:dataTeam ; + odrl:target ex:marketPrices ; + dprod:state dprod:Active . +``` + +### Step 2: Add Provider Duties (SLAs) + +Provider duties declare what the data team commits to. The provider is identified by `dprod:subject` on each duty. Use `dprod:object` to identify who is affected (e.g., who receives notifications). + +Rules inherit `odrl:target` from the policy unless they target a different asset. + +```turtle + # Daily delivery by 06:30 (target inherited from policy) + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:deliver ; + dprod:recurrence "FREQ=DAILY;BYHOUR=6;BYMINUTE=0" ; + dprod:deadline "PT30M"^^xsd:duration + ] ; + + # Schema conformance (different target -- not inherited) + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:conformTo ; + odrl:target ex:marketDataSchema + ] ; +``` + +### Step 3: Add Consumer Permissions + +Permissions define what subscribers can do. In an Offer, omit `odrl:assignee` -- it is filled when the subscription is created. Target is inherited from the policy. + +```turtle + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:display + ] ; + + odrl:permission [ + a odrl:Permission ; + odrl:action dprod-due:nonDisplay ; + odrl:constraint [ + a odrl:Constraint ; + odrl:leftOperand dprod-due:recipientType ; + odrl:operator odrl:eq ; + odrl:rightOperand dprod-due:internal + ] + ] ; +``` + +### Step 4: Add Consumer Duties and Prohibitions + +Consumer duties activate upon subscription. Prohibitions apply to all subscribers. + +```turtle + # Consumer must report usage monthly (different target -- not inherited) + odrl:obligation [ + a odrl:Duty ; + odrl:action dprod-due:report ; + odrl:target ex:usageStats ; + dprod:deadline "P30D"^^xsd:duration + ] ; + + # No external redistribution (target inherited from policy) + odrl:prohibition [ + a odrl:Prohibition ; + odrl:action odrl:distribute + ] . +``` + +### Step 5: Create a Subscription + +When a consumer accepts the contract, create a Subscription (Agreement) referencing the contract: + +```turtle +ex:subscription a dprod:Subscription ; + odrl:profile , + ; + dprod:subscribesTo ex:contract ; + odrl:assigner ex:dataTeam ; + odrl:assignee ex:analyticsTeam ; + dprod:effectiveDate "2026-02-01T00:00:00Z"^^xsd:dateTime ; + dprod:expirationDate "2026-12-31T23:59:59Z"^^xsd:dateTime . +``` + +The subscription materializes all duties from the contract with explicit `dprod:subject` on each. + +--- + +## Provider Duty Patterns + +### Timeliness Pattern (Delivery SLA) + +Scheduled data delivery with a fulfillment window. Target inherited from policy. + +```turtle +odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:deliver ; + dprod:recurrence "FREQ=DAILY;BYHOUR=6;BYMINUTE=0" ; + dprod:deadline "PT30M"^^xsd:duration +] . +``` + +**DCON equivalent**: `ProviderTimelinessPromise` + +### Schema Pattern (Schema Conformance) + +Provider guarantees data conforms to a published schema. Target differs from policy -- specify explicitly. + +```turtle +odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:conformTo ; + odrl:target ex:marketDataSchema +] . +``` + +**DCON equivalent**: `ProviderSchemaPromise` + +### Notification Pattern (Change Notification) + +Provider must notify consumers before making changes, with a lead time expressed as a duration deadline. Use `dprod:object` to identify who is notified. + +```turtle +odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + dprod:object ex:consumer ; + odrl:action dprod-due:notify ; + odrl:target ex:schemaChanges ; + dprod:deadline "P14D"^^xsd:duration +] . +``` + +**DCON equivalent**: `ProviderChangeNotificationPromise` + +### Quality SLA Pattern + +Provider guarantees data quality via `conformTo` with a constraint. This replaces DCON's `ProviderQualityPromise`. + +```turtle +odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:conformTo ; + odrl:target ex:riskMetricsSchema ; + odrl:constraint [ + a odrl:Constraint ; + odrl:leftOperand dprod-due:timeliness ; + odrl:operator odrl:eq ; + odrl:rightOperand dprod-due:realtime + ] +] . +``` + +The constraint can check any DUE operand -- timeliness, classification, environment, etc. + +--- + +## Recurrence + +Recurring duties use `dprod:recurrence` -- an RFC 5545 RRULE string. Combined with `dprod:deadline`, this defines a schedule and fulfillment window. + +```turtle +odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:deliver ; + dprod:recurrence "FREQ=DAILY;BYHOUR=6;BYMINUTE=0" ; + dprod:deadline "PT30M"^^xsd:duration +] . +``` + +This means: deliver market prices daily at 06:00 (target inherited from policy), with a 30-minute window to fulfill. + +### Common RRULE Patterns + +| Pattern | RRULE | +|---------|-------| +| Daily at 06:00 | `FREQ=DAILY;BYHOUR=6;BYMINUTE=0` | +| Weekly on Monday | `FREQ=WEEKLY;BYDAY=MO` | +| Monthly on the 1st | `FREQ=MONTHLY;BYMONTHDAY=1` | +| Every 15 minutes | `FREQ=MINUTELY;INTERVAL=15` | +| Hourly | `FREQ=HOURLY` | + +Each generated instance follows the standard duty lifecycle independently (Pending -> Active -> Fulfilled/Violated). + +--- + +## Common Patterns Quick Reference + +### Simple File Drop + +Read-only access, no recurrence, no consumer duties. Target inherited from policy. + +```turtle +ex:contract a dprod:DataContract ; + odrl:profile ; + odrl:assigner ex:dataTeam ; + odrl:target ex:referenceData ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:read + ] ; + odrl:prohibition [ + a odrl:Prohibition ; + odrl:action odrl:modify + ] . +``` + +### API with SLA + +Daily delivery, schema conformance, display + non-display, monthly reporting. Target inherited from policy unless overridden. + +```turtle +ex:contract a dprod:DataContract ; + odrl:profile , + ; + odrl:assigner ex:dataTeam ; + odrl:target ex:customerData ; + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:deliver ; + dprod:recurrence "FREQ=DAILY;BYHOUR=7;BYMINUTE=0" ; + dprod:deadline "PT30M"^^xsd:duration + ] ; + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:conformTo ; + odrl:target ex:customerSchema + ] ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:display + ] ; + odrl:permission [ + a odrl:Permission ; + odrl:action dprod-due:nonDisplay + ] ; + odrl:obligation [ + a odrl:Duty ; + odrl:action dprod-due:report ; + odrl:target ex:usageStats ; + dprod:deadline "P30D"^^xsd:duration + ] ; + odrl:prohibition [ + a odrl:Prohibition ; + odrl:action odrl:distribute + ] . +``` + +### Mission-Critical Service + +High-frequency delivery with quality SLA and change notification. Target inherited from policy unless overridden. + +```turtle +ex:contract a dprod:DataContract ; + odrl:profile , + ; + odrl:assigner ex:dataTeam ; + odrl:target ex:riskMetrics ; + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:deliver ; + dprod:recurrence "FREQ=MINUTELY;INTERVAL=1" ; + dprod:deadline "PT30S"^^xsd:duration + ] ; + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:conformTo ; + odrl:target ex:riskSchema ; + odrl:constraint [ + a odrl:Constraint ; + odrl:leftOperand dprod-due:timeliness ; + odrl:operator odrl:eq ; + odrl:rightOperand dprod-due:realtime + ] + ] ; + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:notify ; + odrl:target ex:schemaChanges ; + dprod:deadline "P14D"^^xsd:duration + ] ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:display + ] ; + odrl:permission [ + a odrl:Permission ; + odrl:action dprod-due:nonDisplay + ] . +``` + +### Multi-Dataset Contract + +A single contract covering multiple targets. When a policy has multiple targets, rules must specify their target explicitly -- inheritance is ambiguous. + +```turtle +ex:contract a dprod:DataContract ; + odrl:profile ; + odrl:assigner ex:dataTeam ; + odrl:target ex:marketPrices , ex:referenceData , ex:riskMetrics ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:read ; + odrl:target ex:marketPrices + ] ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:read ; + odrl:target ex:referenceData + ] ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:read ; + odrl:target ex:riskMetrics + ] . +``` + +--- + +## Advanced Topics + +### Target Inheritance + +`odrl:target` at the policy level is inherited by rules that don't declare their own target. This reduces redundancy: + +```turtle +ex:contract a dprod:DataContract ; + odrl:target ex:marketPrices ; # policy-level target + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:read # inherits ex:marketPrices + ] ; + odrl:obligation [ + a odrl:Duty ; + dprod:subject ex:dataTeam ; + odrl:action dprod-due:conformTo ; + odrl:target ex:marketDataSchema # different target -- explicit + ] . +``` + +**Rules**: +- Single-target policy: rules inherit the target unless they specify a different one +- Multi-target policy: rules must specify their target (inheritance is ambiguous) +- Named duty instances (standalone): always specify their target + +### Multi-Asset Contracts + +A contract can cover multiple targets. When multiple targets exist, each rule must specify its own target (inheritance is ambiguous): + +```turtle +ex:contract odrl:target ex:asset1 , ex:asset2 ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:read ; + odrl:target ex:asset1 + ] ; + odrl:permission [ + a odrl:Permission ; + odrl:action odrl:display ; + odrl:target ex:asset2 + ] . +``` + +### Team Delegation + +Use `dprod:memberOf` to model team hierarchies. A permission granted to a team applies to its members via hierarchy subsumption during evaluation: + +```turtle +ex:analyst a odrl:Party ; + dprod:memberOf ex:analyticsTeam . + +ex:analyticsTeam a odrl:Party ; + dprod:memberOf ex:tradingDivision . +``` + +### Version Chains + +Use `prov:wasRevisionOf` to link contract versions: + +```turtle +ex:contract-v2 a dprod:DataContract ; + prov:wasRevisionOf ex:contract-v1 . + +ex:contract-v3 a dprod:DataContract ; + prov:wasRevisionOf ex:contract-v2 . +``` + +Subscriptions reference the specific contract version they activate: + +```turtle +ex:subscription dprod:subscribesTo ex:contract-v2 . +``` + +### Expiration + +Contracts and subscriptions can have explicit expiration dates: + +```turtle +ex:subscription a dprod:Subscription ; + dprod:effectiveDate "2026-01-15T00:00:00Z"^^xsd:dateTime ; + dprod:expirationDate "2026-12-31T23:59:59Z"^^xsd:dateTime . +``` + +--- + +## Lifecycle + +Duties and contracts share four states: + +``` + condition true +Pending ──────────────> Active + | | + action done | | deadline passed + v v + Fulfilled Violated +``` + +- **Pending**: condition not yet met / not yet in force +- **Active**: condition met, action required / in force +- **Fulfilled**: action performed / obligations complete +- **Violated**: deadline passed / breached + +--- + +## Versioning + +Contracts can be versioned using `prov:wasRevisionOf`: + +```turtle +ex:contract-v2 a dprod:DataContract ; + prov:wasRevisionOf ex:contract-v1 . +``` + +Subscriptions reference the contract they activate via `dprod:subscribesTo`: + +```turtle +ex:subscription dprod:subscribesTo ex:contract-v2 . +``` + +--- + +## Complete Example + +See [examples/data-contract.ttl](../examples/data-contract.ttl) for a full working contract with bilateral duties, recurrence, schema conformance, and subscription. + +For comprehensive test data covering all patterns, see [examples/baseline.ttl](../examples/baseline.ttl). + +--- + +## DCON Migration + +If migrating from DCON, see [term-mapping.md](term-mapping.md) for complete property equivalents. + +--- + +## Validation Checklist + +1. Every policy declares `odrl:profile ` and `` +2. Conflict strategy (`odrl:conflict odrl:prohibit`) is inherited from the profile -- do not repeat per-policy +3. DataContract has `odrl:assigner` (provider) +4. Subscription has both `odrl:assigner` and `odrl:assignee` +5. Subscription has `dprod:subscribesTo` referencing a DataContract +6. Each duty has exactly one `odrl:action` +7. Each permission and prohibition has exactly one `odrl:action` and one `odrl:target` +8. Provider duties have `dprod:subject` set to the provider +9. Deadlines use `xsd:dateTime` or `xsd:duration` +10. Recurrence uses a valid RFC 5545 RRULE starting with `FREQ=` +11. Constraints have `leftOperand`, `operator`, and `rightOperand` +12. LogicalConstraints use exactly one of `odrl:and`, `odrl:or`, or `dprod:not` +13. Validate against SHACL shapes: + +```bash +shacl validate --shapes dprod-contracts-shapes.ttl --data my-contract.ttl +``` diff --git a/dprod-contracts/docs/display.html b/dprod-contracts/docs/display.html deleted file mode 100644 index cf052a0..0000000 --- a/dprod-contracts/docs/display.html +++ /dev/null @@ -1,126 +0,0 @@ - - - - DPROD Ontology Interactive Map - - - - - -

🧠 DPROD Ontology Explorer

-
- Core - Promises - Actions - Status -
- -
- - - - \ No newline at end of file diff --git a/dprod-contracts/docs/formal-semantics.md b/dprod-contracts/docs/formal-semantics.md new file mode 100644 index 0000000..e920add --- /dev/null +++ b/dprod-contracts/docs/formal-semantics.md @@ -0,0 +1,1127 @@ +--- +title: "DPROD Contracts Formal Semantics" +subtitle: "Deterministic Policy Evaluation for Data Governance" +version: "0.7" +status: "Draft" +date: 2026-02-03 +abstract: | + DPROD Contracts is a proper ODRL 2.2 profile with deterministic, total evaluation + semantics and bilateral agreement support. This document specifies the formal + semantics in a style amenable to mechanization in Dafny, Why3, or similar + verification frameworks. +--- + +## 1. Introduction + +DPROD Contracts addresses semantic gaps in ODRL 2.2: + +1. **Duty Ambiguity**: ODRL conflates pre-conditions with post-obligations +2. **Unilateral Agreements**: ODRL evaluates only from assignee perspective +3. **Undefined States**: ODRL permits evaluation to be "undefined" + +DPROD Contracts provides: + +- Explicit duty lifecycle with state machine semantics +- Bilateral agreement evaluation (grantor and grantee duties) +- Total evaluation functions (always terminate with defined result) +- Clear separation of Condition (pre-requisite) from Duty (obligation) +- Path-based operand resolution with formal grammar and security constraints + +### 1.1 Scope and Runtime Boundary + +This specification defines **evaluation semantics** — the contract a conformant engine +must satisfy. The `State` parameter in `Eval` is an opaque input provided by the +runtime environment. DPROD Contracts specifies what decision and state transitions *should* +result from evaluation, but does not define: + +- How `State` is persisted or managed between evaluations +- Event-driven triggers for duty activation or deadline enforcement +- Protocols for requirement fulfillment claims or re-evaluation + +These operational concerns are out of scope for a declarative policy profile. +Implementations requiring runtime state management, event processing, and enforcement +protocols should consult RL2, which extends DPROD Contracts's evaluation semantics with a +complete operational protocol layer. + +### 1.2 Notation + +- `×` for Cartesian product +- `→` for function types +- `∪` for union +- `∈` for set membership +- `⊥` for undefined/bottom value +- `⟦e⟧` for denotation of expression `e` +- `Γ ⊢ e : τ` for typing judgement ("in context Γ, expression e has type τ") + +### 1.2 Document Status + +This document is **normative** for DPROD Contracts implementations. + +--- + +## 2. Type System + +The type system ensures well-formed policies. + +### 2.1 Typing Judgements + +We use: + +``` +Γ ⊢ e : τ +``` + +Where Γ is a typing context mapping identifiers to types. + +### 2.2 Types + +``` +τ ::= Agent | Action | Asset | Condition | Time | Duration | Boolean | Value | Norm | State | Policy +``` + +### 2.3 Key Typing Rules + +Permission: + +``` +Γ ⊢ a : Agent Γ ⊢ x : Action Γ ⊢ s : Asset Γ ⊢ c : Condition +--------------------------------------------------------------------------- + Γ ⊢ Permission(a, x, s, c) : Norm +``` + +Duty: + +``` +Γ ⊢ a : Agent Γ ⊢ x : Action Γ ⊢ s : Asset +Γ ⊢ c : Condition Γ ⊢ dl : Deadline Γ ⊢ r : Recurrence +-------------------------------------------------------------------------- + Γ ⊢ Duty(a, x, s, c, dl, r) : Norm +``` + +Prohibition: + +``` +Γ ⊢ a : Agent Γ ⊢ x : Action Γ ⊢ s : Asset Γ ⊢ c : Condition +--------------------------------------------------------------------------- + Γ ⊢ Prohibition(a, x, s, c) : Norm +``` + +AtomicConstraint: + +``` +Γ ⊢ left : LeftOperand Γ ⊢ op : ComparisonOperator Γ ⊢ right : Value +------------------------------------------------------------------------------- + Γ ⊢ AtomicConstraint(left, op, right) : Condition +``` + +Logical connectives follow standard typing rules for Boolean-valued expressions. + +--- + +## 3. Abstract Syntax + +We define DPROD Contracts's abstract syntax using a typed algebraic grammar. + +### 3.1 Syntactic Domains + +| Domain | Symbol | Description | +|--------|--------|-------------| +| Agents | **A** | Set of agent identifiers | +| Actions | **X** | Set of action identifiers | +| Assets | **S** | Set of asset identifiers | +| Values | **V** | Set of atomic values (strings, numbers, URIs) | +| Time | **T** | Time domain (ISO 8601 instants) | +| Duration | **D** | Duration domain (ISO 8601 durations) | + +### 3.2 Norms + +``` +Norm ::= Permission(subject: Agent, action: Action, asset: Asset, condition: Condition?) + | Duty(subject: Agent, action: Action, asset: Asset, + object: Agent?, condition: Condition?, deadline: Deadline?, recurrence: Recurrence?) + | Prohibition(subject: Agent, action: Action, asset: Asset, condition: Condition?) + +Deadline ::= AbsoluteDeadline(time: Time) + | RelativeDeadline(duration: Duration) + +Recurrence ::= RRule(rule: String) +``` + +**Notes**: + +- `Permission` corresponds to `odrl:Permission`; `Prohibition` to `odrl:Prohibition`; `Duty` to `odrl:Duty`. +- The formal `subject` parameter maps to `dprod:subject` on duties (rdfs:subPropertyOf `odrl:assignee`) and to `odrl:assignee` on permissions/prohibitions. +- The formal `object` parameter (duties only) maps to `dprod:object` — the party affected by the duty action (e.g., who is notified). Not used in norm matching. +- `AbsoluteDeadline`: Fixed point in time (e.g., 2026-12-31T23:59:59Z) +- `RelativeDeadline`: Duration from activation (e.g., P30D, PT24H) + +**Abstract-to-RDF Name Mapping**: + +| Abstract Syntax | RDF Encoding | Notes | +|---|---|---| +| `Permission` | `odrl:Permission` | | +| `Duty` | `odrl:Duty` | | +| `Prohibition` | `odrl:Prohibition` | | +| `subject` (Permission/Prohibition) | `odrl:assignee` | Party to whom the norm applies | +| `subject` (Duty) | `dprod:subject` | Party bearing the duty (rdfs:subPropertyOf odrl:assignee) | +| `object` (Duty) | `dprod:object` | Party affected by the duty action (metadata, not used in matching) | +| `grantor` | `odrl:assigner` | Party granting rights | +| `grantee` | `odrl:assignee` | Party receiving rights (policy-level) | +| `condition` | `odrl:constraint` | | +| `Set` | `odrl:Set` | | +| `Offer` | `odrl:Offer` | `DataContract` is a subtype | +| `Agreement` | `odrl:Agreement` | `Subscription` is a subtype | +| `lte` | `odrl:lteq` | | +| `gte` | `odrl:gteq` | | +| `recurrence` | `dprod:recurrence` | RFC 5545 RRULE string | + +### 3.3 Conditions + +``` +Condition ::= AtomicConstraint(leftOperand: LeftOperand, + operator: ComparisonOperator, + rightOperand: Value) + | And(operands: Condition+) + | Or(operands: Condition+) + | Not(operand: Condition) + +ComparisonOperator ::= eq | neq | lt | lte | gt | gte | isAnyOf | isNoneOf + +RuntimeRef ::= currentAgent | currentDateTime +``` + +**Notes**: + +- `leftOperand` is drawn from profile-defined operands with `resolutionPath`, or dual-typed `RuntimeReference` operands (e.g., `currentDateTime`) +- Dynamic value resolution on the left side uses `LeftOperand` with `dprod:resolutionPath` or dual-typed `RuntimeReference` operands resolved via `resolveRuntime` +- Right operands are literal values. Identity binding via runtime references in right-operand position is deferred to RL2 (`rl2:rightOperandRef`) + +### 3.4 Policies + +``` +Policy ::= Set(target: Asset?, clauses: Norm+, condition: Condition?) + | Offer(grantor: Agent, grantee: Agent?, target: Asset?, clauses: Norm+, condition: Condition?) + | Agreement(grantor: Agent, grantee: Agent, target: Asset?, clauses: Norm+, condition: Condition?) +``` + +**Notes**: + +- `Set`: Unilateral declaration, no parties. Maps to `odrl:Set` in the RDF encoding. +- `Offer`: Proposal from grantor, grantee optional (open offer). Maps to `odrl:Offer`. `DataContract` is a subtype of `Offer`. +- `Agreement`: Bilateral binding, both parties identified. Maps to `odrl:Agreement`. `Subscription` is a subtype of `Agreement`. +- The formal `grantor` parameter maps to `odrl:assigner` (the party granting rights) in the RDF encoding. +- The formal `grantee` parameter maps to `odrl:assignee` (the party receiving rights) in the RDF encoding. + +### 3.5 Requests + +``` +Request ::= Request(agent: Agent, action: Action, asset: Asset, context: Context) + +Context ::= Map +``` + +**Note**: Context keys correspond to the second segment of resolution paths (e.g., the path `context.purpose` resolves by looking up `"purpose"` in `Context`). + +--- + +## 4. Semantic Domains + +### 4.1 State + +``` +Σ = { + clock : Time, + state : Duty → State, + activatedAt : Duty → Time?, // When duty became Active + performed : Set<(Agent, Action, Asset, Time)> +} + +State ::= Pending | Active | Fulfilled | Violated +``` + +**Notes**: + +- `State` is a unified lifecycle enum shared by duties, contracts, and subscriptions. The formal semantics tracks duty state during evaluation; contract and subscription state is administrative (not evaluated at request time). +- Terminal states (`Fulfilled`, `Violated`) are permanent — see §9.4. + +**Initial state** Σ₀: + +``` +Σ₀ = { + clock = currentSystemTime, + state = λd. Pending, + activatedAt = λd. ⊥, + performed = ∅ +} +``` + +**State Update Notation**: We use `Σ[f ↦ v]` to denote state update: + +``` +Σ[state(d) ↦ Active] = + (Σ.clock, Σ.state[d ↦ Active], Σ.activatedAt, Σ.performed) + +Σ[state(d) ↦ Active, activatedAt(d) ↦ t] = + (Σ.clock, Σ.state[d ↦ Active], Σ.activatedAt[d ↦ t], Σ.performed) +``` + +### 4.2 Environment + +``` +Env = { + agent : Agent, // Canonical root: agent + action : Action, + asset : Asset, // Canonical root: asset + context : Context, // Canonical root: context + Σ : Σ +} +``` + +The three canonical roots (`agent`, `asset`, `context`) are the entry points for `deref` path resolution (see §6.3). + +**Environment Construction**: Given a Request `R = (a, x, s, ctx)` and state Σ: + +``` +buildEnv(R, Σ) = { + agent = R.agent, + action = R.action, + asset = R.asset, + context = R.context, + Σ = Σ +} +``` + +### 4.3 Decision + +``` +Decision ::= Permit | Deny | NotApplicable +``` + +### 4.4 Evaluation Result + +``` +Result = { + decision : Decision, + grantorDuties : Set, // Duties on the grantor (data provider) + granteeDuties : Set, // Duties on the grantee (data consumer) + violations : Set, + explanation : Explanation +} +``` + +--- + +## 5. Duty Lifecycle + +### 5.1 State Diagram + +``` + condition becomes true + ┌─────────────────────────────────────┐ + │ ▼ + ┌───────┐ ┌────────┐ + │Pending│ │ Active │ + └───────┘ └────────┘ + │ │ + action performed │ │ deadline exceeded + ▼ ▼ + ┌──────────┐ ┌─────────┐ + │Fulfilled │ │Violated │ + └──────────┘ └─────────┘ +``` + +### 5.2 Transition Rules + +**Rule D-ACTIVATE** (Pending → Active): + +``` +Σ.state(duty) = Pending +duty.condition = ⊥ ∨ ⟦duty.condition⟧(Env) = true +───────────────────────────────────────────────── +Σ' = Σ[state(duty) ↦ Active, activatedAt(duty) ↦ Σ.clock] +``` + +Activation is **condition-driven**: when the duty's condition first evaluates to true (or the duty has no condition), the duty becomes active. + +**Rule D-FULFILL** (Active → Fulfilled): + +``` +Σ.state(duty) = Active +performed(duty.subject, duty.action, duty.asset, Σ) = true +effectiveDeadline(duty, Σ) ≥ Σ.clock ∨ effectiveDeadline(duty, Σ) = ∞ +──────────────────────────────────────────────────────────────────────── +Σ' = Σ[state(duty) ↦ Fulfilled] +``` + +Fulfillment is **event-driven**: when a performed action matches the duty's required action (including narrower actions via `includedIn` subsumption), the duty is fulfilled. + +**Rule D-VIOLATE** (Active → Violated): + +``` +Σ.state(duty) = Active +Σ.clock > effectiveDeadline(duty, Σ) +performed(duty.subject, duty.action, duty.asset, Σ) = false +──────────────────────────────────────────────────────────── +Σ' = Σ[state(duty) ↦ Violated] +``` + +Violation is **time-driven**: when the deadline passes without fulfillment, the duty is violated. + +**Algorithmic form** (for implementation): + +``` +updateDutyStates(duties, Env, Σ) = + foldl(updateOneDuty(Env), Σ, duties) + +updateOneDuty(Env)(Σ, d) = + case Σ.state(d) of + Pending → if d.condition = ⊥ ∨ ⟦d.condition⟧(Env) + then Σ[state(d) ↦ Active, activatedAt(d) ↦ Σ.clock] + else Σ + Active → if performed(d.subject, d.action, d.asset, Σ) + then Σ[state(d) ↦ Fulfilled] + else if Σ.clock > effectiveDeadline(d, Σ) + then Σ[state(d) ↦ Violated] + else Σ + _ → Σ -- Fulfilled/Violated are terminal +``` + +### 5.3 Effective Deadline + +``` +effectiveDeadline(duty, Σ) = + case duty.deadline of + ⊥ → ∞ + AbsoluteDeadline(t) → t + RelativeDeadline(d) → Σ.activatedAt(duty) + d +``` + +### 5.4 Match Semantics + +Action and asset matching support hierarchy subsumption: + +``` +x₁ matches x₂ ⟺ x₁ = x₂ ∨ x₁ includedIn⁺ x₂ +s₁ matches s₂ ⟺ s₁ = s₂ ∨ s₁ partOf⁺ s₂ +``` + +Where `includedIn⁺` and `partOf⁺` are the transitive closures of `odrl:includedIn` and `dprod:partOf` respectively. + +Agent matching supports hierarchy subsumption: + +``` +a₁ matches a₂ ⟺ a₁ = a₂ ∨ a₁ memberOf⁺ a₂ +``` + +Where `memberOf⁺` is the transitive closure of `dprod:memberOf`. + +The subsumption-aware performed check is: + +``` +performed(a, x, s, Σ) := + ∃(a', x', s', t) ∈ Σ.performed : + a' = a ∧ (x' = x ∨ x' includedIn⁺ x) ∧ s' matches s +``` + +`Σ.performed` records exact actions as they occur. `performed()` is the query-time subsumption check used in all fulfillment and violation rules. This is a bounded graph traversal over the `odrl:includedIn` hierarchy. + +### 5.5 Recurrence Semantics + +A duty with a `recurrence` field defines a recurring obligation. The recurrence value is an RFC 5545 RRULE string (e.g., `FREQ=DAILY;BYHOUR=6;BYMINUTE=0`). + +**Instance Generation**: + +``` +expand : Recurrence × Time → Set