README.md

prov2ld

A lightweight Python script to convert PROV-JSON documents to PROV-JSONLD format according to the W3C PROV-JSONLD specification.
Report Bug · Request Feature

Requirements

For the ld2viz command, the library requires the GraphViz suite. For everything to correctly work, this module has to be installed. We reference both the installation section on their docs, as well as the main ways to install it.

Linux

sudo apt install graphviz

MacOS

# Installing Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install graphviz

Windows

Installers are at the Download page of GraphViz.

Installation

pip install prov2ld

Basic Usage

1. Convert a file to Prov-JSONLD

python -m prov2ld input.json output.jsonld
# Basic example from the PROV-PRIMER
python -m prov2ld example/test_comprehensive.json example/test_comprehensive.jsonld

2. Convert Prov-JSONLD to Graph Visualization

python -m ld2viz input.jsonld output.png
# Or: 
python -m prov2ld example/test_comprehensive.jsonld example/test_comprehensive.png

What Gets Converted?

Input (PROV-JSON)

{
  "prefix": {
    "ex": "http://example.org/",
    "prov": "http://www.w3.org/ns/prov#"
  },
  "entity": {
    "ex:e1": {}
  },
  "activity": {
    "ex:a1": {}
  },
  "wasGeneratedBy": {
    "_:gen1": {
      "prov:entity": "ex:e1",
      "prov:activity": "ex:a1"
    }
  }
}

Output (PROV-JSONLD)

{
  "@context": [
    {
      "ex": "http://example.org/",
      "prov": "http://www.w3.org/ns/prov#"
    },
    "https://openprovenance.org/prov-jsonld/context.json"
  ],
  "@graph": [
    {
      "@type": "prov:Entity",
      "@id": "ex:e1"
    },
    {
      "@type": "prov:Activity",
      "@id": "ex:a1"
    },
    {
      "@type": "prov:Generation",
      "@id": "_:gen1",
      "entity": "ex:e1",
      "activity": "ex:a1"
    }
  ]
}

PROV Elements Supported

Core Elements

• Entities (prov:Entity)
• Activities (prov:Activity)
• Agents (prov:Agent)

Relations

• Generation (prov:Generation) - wasGeneratedBy
• Usage (prov:Usage) - used
• Communication (prov:Communication) - wasInformedBy
• Start (prov:Start) - wasStartedBy
• End (prov:End) - wasEndedBy
• Invalidation (prov:Invalidation) - wasInvalidatedBy
• Derivation (prov:Derivation) - wasDerivedFrom
• Attribution (prov:Attribution) - wasAttributedTo
• Association (prov:Association) - wasAssociatedWith
• Delegation (prov:Delegation) - actedOnBehalfOf
• Influence (prov:Influence) - wasInfluencedBy
• Specialization (provext:Specialization) - specializationOf
• Alternate (provext:Alternate) - alternateOf
• Membership (provext:Membership) - hadMember

Additional Features

• Custom attributes with namespaces
• Typed values
• Language-tagged strings
• Time attributes (startTime, endTime, time)
• PROV bundles
• Roles, types, labels, and locations

Support

This converter implements the PROV-JSONLD specification from: Moreau, L., & Huynh, T. D. (2021). The PROV-JSONLD Serialization

For questions about PROV itself, see:

• PROV Overview
• PROV-DM Specification
• PROV-O Ontology
• PROV-JSON Submission
• JSON-LD 1.1 Specification
• PROV-JSONLD Context

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.