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

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, 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, 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:

# 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:

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 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:

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 – Defines the ProvenanceEntry Pydantic schema that validates and serializes provenance records to JSON
• semantica/provenance/manager.py – Handles persistent storage of provenance entries, typically as JSON records in the provenance store
• 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.
• 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 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 (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—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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}