# What Format Does Semantica Use for Exporting Provenance Data for Regulatory Compliance?

> Semantica exports provenance data in JSON format for regulatory compliance. Discover how it captures audit trails with timestamps and metadata.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: faq
- Published: 2026-09-13

---

**Semantica exports provenance data in JSON format as the default and recommended standard for regulatory compliance, using the `ExporterWithProvenance` wrapper to capture audit trails with ISO-8601 timestamps, entity metadata, and operation details.**

The `semantica-agi/semantica` repository provides robust provenance tracking capabilities designed specifically for regulatory audit requirements. When exporting data with provenance enabled, the system defaults to JSON to ensure machine-readable output that complies with transparency and traceability standards.

## JSON as the Default Provenance Export Format

According to the source code in [`semantica/export/export_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/export_provenance.py), Semantica treats **JSON** as the canonical format for provenance-enabled exports. The implementation explicitly defaults to `"json"` when no format is specified (lines 64‑66), making it the standard choice for regulatory compliance workflows.

The `JSONExporterWithProvenance` class provides a high-level interface that automatically serializes both the data and its provenance record into a single JSON output file. This approach ensures that audit trails remain human-readable while maintaining strict schema compliance for automated processing systems.

## How the ExporterWithProvenance Wrapper Works

The provenance-enabled export wrapper tracks critical metadata about every export operation. When you initialize an exporter with `provenance=True`, the system records:

- **Destination path** and **file format**
- **ISO-8601 timestamps** for operation start and end times
- **Agent identification** (the exporter class name)
- **Entity classification** and unique identifiers

### Core Implementation Details

In [`semantica/export/export_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/export_provenance.py), the base `ExporterWithProvenance` class handles the provenance recording logic. The constructor accepts a `provenance` boolean flag that activates tracking. When exporting, the wrapper intercepts the operation to generate a provenance entry before writing the final JSON output.

The default format logic appears in the export method:

```python

# Default format is "json" if not specified (lines 64-66 in export_provenance.py)

if format is None:
    format = "json"

```

This ensures regulatory compliance exports consistently use JSON unless explicitly overridden.

## Provenance Record Structure in JSON

Each provenance export produces a JSON object containing the following standardized fields:

- **`entity_id`** – Unique identifier for the exported dataset
- **`source`** – Fixed value `export_operation` indicating the activity type
- **`entity_type`** – Classification as `export`
- **`agent_id`** – String name of the exporter class (e.g., `JSONExporterWithProvenance`)
- **`activity_started_at_time`** – ISO-8601 timestamp when export began
- **`activity_ended_at_time`** – ISO-8601 timestamp when export completed
- **`metadata`** – Object containing destination path and format specifications

These fields align with W3C PROV standards, making the output suitable for regulatory submissions that require complete lineage tracking.

## Practical Code Examples for Regulatory Compliance

### Exporting Knowledge Graphs with Full Provenance

Use the specialized JSON exporter to capture complete audit trails for knowledge graph exports:

```python
from semantica.export.export_provenance import JSONExporterWithProvenance

kg = load_knowledge_graph()  # Your knowledge graph object

exporter = JSONExporterWithProvenance(provenance=True)
exporter.export(kg, "kg_regulatory_audit.json")

```

This creates [`kg_regulatory_audit.json`](https://github.com/semantica-agi/semantica/blob/main/kg_regulatory_audit.json) containing both the graph data and a nested provenance record suitable for compliance documentation.

### Generic Export with Explicit Format Control

For scenarios requiring explicit format specification while maintaining provenance tracking:

```python
from semantica.export.export_provenance import ExporterWithProvenance

exporter = ExporterWithProvenance(provenance=True)
exporter.export(sensitive_data, "compliance_export.json", format="json")

```

Both examples generate JSON files that satisfy regulatory requirements for data lineage and export traceability.

## Supporting Infrastructure for Provenance Tracking

Several modules in the Semantica codebase support the JSON provenance export system:

- **[`semantica/provenance/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/schemas.py)** – Defines the `ProvenanceEntry` Pydantic schema that validates and serializes provenance records to JSON
- **[`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py)** – Handles persistent storage of provenance entries, typically as JSON records in the provenance store
- **[`semantica/visualization/visualization_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/visualization_provenance.py)** – Demonstrates provenance tracking for visualization exports using the same JSON serialization patterns

This architecture ensures consistency across all export types, from raw data dumps to visualization assets, maintaining a unified JSON-based audit trail format.

## Summary

- Semantica defaults to **JSON format** for all provenance-enabled exports, as implemented in [`semantica/export/export_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/export_provenance.py).
- The `ExporterWithProvenance` wrapper automatically records **ISO-8601 timestamps**, **entity IDs**, and **operation metadata** in every export.
- **Regulatory compliance** requirements are met through standardized JSON structures containing complete lineage information.
- The `ProvenanceEntry` schema in [`semantica/provenance/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/schemas.py) ensures consistent serialization across data, knowledge graphs, and visualization exports.

## Frequently Asked Questions

### What is the default file format for Semantica provenance exports?

JSON is the default and recommended format. According to the source code in [`semantica/export/export_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/export_provenance.py) (lines 64‑66), the export method defaults to `"json"` when no format parameter is provided, ensuring consistent machine-readable output for regulatory systems.

### Can Semantica export provenance data in formats other than JSON?

While the underlying `ExporterWithProvenance` class accepts a `format` parameter, the implementation specifically optimizes for JSON serialization through the `JSONExporterWithProvenance` class. The provenance records themselves—defined in [`semantica/provenance/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/schemas.py)—are designed around JSON Schema standards, making JSON the native and most reliable format for compliance exports.

### What specific metadata does Semantica include in provenance JSON records?

Each provenance JSON record includes: a unique `entity_id`, `source` classification (`export_operation`), `entity_type` (`export`), the `agent_id` (exporter class name), precise `activity_started_at_time` and `activity_ended_at_time` timestamps in ISO-8601 format, and a `metadata` object capturing the destination path and file format used.

### Which Semantica module handles provenance storage for compliance audits?

The [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py) module manages the storage lifecycle of provenance entries, typically persisting them as JSON records. This integrates with the export system to ensure that every data export generates a corresponding immutable audit trail suitable for regulatory review.