# How to Export Decisions to W3C PROV-O Format from Semantica

> Export Semantica decisions to W3C PROV-O format using the CLI or API. Serialize decision lineage as RDF triples in Turtle, RDF/XML, or JSON-LD.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-09

---

**Use the `semantica export provenance` CLI command or call `ProvenanceManager.export()` to serialize decision lineage as W3C PROV-O RDF triples in Turtle, RDF/XML, or JSON-LD format.**

Semantica is an open-source AI governance framework that records the *who*, *what*, when, and *why* behind automated decisions. When audit requirements or data lineage standards demand standards-compliant provenance traces, you can export decisions to W3C PROV-O format using the built-in provenance manager and RDF exporter.

## How Provenance Export Works in Semantica

The export pipeline relies on three tightly integrated components defined in the `semantica-agi/semantica` repository:

1. **`ProvenanceManager`** ([`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py)) – The central façade that aggregates decision events and constructs the PROV-O graph.
2. **`RDFExporter`** ([`semantica/export/rdf_exporter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/rdf_exporter.py)) – Handles RDF serialization, namespace binding, and validation.
3. **CLI wrapper** ([`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py)) – Parses user arguments and delegates to the manager.

When a decision is recorded, `ProvenanceManager` creates three core PROV concepts:
- **PROV-Agent** – The actor or system making the decision.
- **PROV-Activity** – The decision-making process itself.
- **PROV-Entity** – The output or artifact produced by the decision.

The manager then wires these together using standard PROV relations such as `prov:wasGeneratedBy`, `prov:wasAssociatedWith`, and `prov:wasDerivedFrom` before handing the graph to the exporter for serialization.

## Exporting Decisions via the Command Line

The fastest way to generate a PROV-O dump is through the `export provenance` sub-command. This invokes the internal `_dry` function in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py), which forwards your parameters to `ProvenanceManager.export()`.

### Basic Syntax

```bash
semantica export provenance \
    --format prov \
    --base-uri https://example.org/semantica/ \
    --output decisions.prov.ttl

```

### Parameter Reference

- `--format` – Serialization format (`prov` for Turtle, or explicit `turtle`, `rdfxml`, `jsonld`, `ntriples`, `n3`).
- `--base-uri` – The IRI prefix used to mint stable identifiers for entities, activities, and agents.
- `--output` – Destination file path; use `-` to stream to stdout.

The CLI validates the format against the supported RDF exporters before invoking the manager, ensuring the output conforms to W3C PROV-O semantics.

## Exporting Decisions Programmatically

For integration within Python workflows, instantiate `ProvenanceManager` directly and invoke its `export()` method.

### Standard Export Workflow

```python
from semantica.provenance.manager import ProvenanceManager

# Initialize with your backend (e.g., sqlite, neo4j)

manager = ProvenanceManager(backend="sqlite")

# ... execute decision workflow ...

# Export to PROV-O Turtle

manager.export(
    format="turtle",
    base_uri="https://example.org/semantica/",
    output_path="decisions.prov.ttl"
)

```

The `export()` method automatically:
- Binds the `prov` namespace to `http://www.w3.org/ns/prov#`
- Creates an `RDFExporter` instance
- Serializes the internal graph using the specified format

### Exporting Specific Decisions

To retrieve and export a single decision’s provenance record, use the `GET_PROVENANCE` schema helper:

```python
from semantica.provenance.manager import ProvenanceManager
from semantica.provenance.schemas import GET_PROVENANCE

manager = ProvenanceManager(backend="sqlite")
decision_id = "decision-uuid-123"

# Fetch specific provenance metadata

prov_data = manager.get_provenance(decision_id)

# Export via RDFExporter

from semantica.export.rdf_exporter import RDFExporter
exporter = RDFExporter()
exporter.export(prov_data, "single.prov.ttl", format="turtle")

```

This approach is defined in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py) and leverages the schema validation found in [`semantica_mcp/mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/schemas.py).

## Understanding the PROV-O Output Structure

The exported RDF graph follows the W3C PROV-O ontology specification. In [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py), the manager constructs triples using the following pattern:

```python
from rdflib import Namespace, Graph
PROV = Namespace("http://www.w3.org/ns/prov#")
g = Graph()
g.bind("prov", PROV)

# Entity representing the decision output

g.add((entity_uri, RDF.type, PROV.Entity))

# Activity representing the decision process

g.add((activity_uri, RDF.type, PROV.Activity))

# Agent representing the decision maker

g.add((agent_uri, RDF.type, PROV.Agent))

# Relations

g.add((entity_uri, PROV.wasGeneratedBy, activity_uri))
g.add((activity_uri, PROV.wasAssociatedWith, agent_uri))

```

Key characteristics of the output:
- **Stable IRIs** – Entities use SHA-256 hashes or UUIDs appended to the `--base-uri` to ensure global uniqueness.
- **Confidence Metadata** – When available, confidence values are attached as custom data properties before normalization by `RDFExporter`.
- **Validation** – The exporter runs a compliance check against PROV-O constraints, ensuring that every `Entity` has a generation activity and every `Activity` has an associated agent.

## Customization and Advanced Options

### Configuring Base URIs for interoperability

The `--base-uri` parameter (or `base_uri` in Python) determines the namespace for all minted identifiers. For production deployments, align this with your organizational URI strategy:

```bash
semantica export provenance \
    --base-uri https://api.yourorg.com/provenance/2024/ \
    --format prov \
    --output lineage.ttl

```

### Supported RDF Formats

While `prov` defaults to Turtle for readability, the `RDFExporter` supports all standard W3C formats:
- **Turtle** (`.ttl`) – Human-readable, default for PROV-O.
- **RDF/XML** (`.rdf`) – Legacy XML serialization.
- **JSON-LD** (`.jsonld`) – Modern linked-data format ideal for web APIs.
- **N-Triples** (`.nt`) – Line-based format for streaming processing.

## Summary

- **Command-line export** is available via `semantica export provenance` with flags for `--format`, `--base-uri`, and `--output`.
- **Programmatic export** uses `ProvenanceManager.export()` in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py), which orchestrates the RDF serialization.
- The implementation binds the `http://www.w3.org/ns/prov#` namespace and generates standard PROV-O triples for entities, activities, and agents.
- Output is validated and normalized by `RDFExporter` in [`semantica/export/rdf_exporter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/rdf_exporter.py), supporting Turtle, RDF/XML, and JSON-LD.

## Frequently Asked Questions

### What is W3C PROV-O and why does Semantica use it?

W3C PROV-O is the OWL2 ontology for representing provenance information on the web. Semantica uses it because it provides a standardized, machine-readable vocabulary for describing the lineage of AI decisions, enabling interoperability with external audit tools and regulatory compliance systems.

### Can I export a subset of decisions rather than the entire provenance graph?

Yes. Use `ProvenanceManager.get_provenance(decision_id)` to retrieve a specific decision’s metadata, then pass that data to `RDFExporter.export()` directly. This avoids serializing the full provenance store when you only need lineage for a single decision trace.

### Which file formats are supported for PROV-O export?

Semantica supports Turtle (the default), RDF/XML, JSON-LD, N-Triples, and N3. Specify your preferred format using the `--format` CLI flag or the `format` parameter in the Python API. Turtle is recommended for human review, while JSON-LD is preferred for API integration.

### How do I validate that my exported file is valid PROV-O?

The `RDFExporter` performs internal validation against PROV-O constraints before writing the file. For external validation, load the exported file into a W3C PROV validator or use an RDF tool like Apache Jena to verify that all required `prov:Entity`, `prov:Activity`, and `prov:Agent` relationships are present and correctly typed.