PROV Validator API Documentation

Old Documentation

Invoking the service

The service endpoint responds to HTTP POST requests at the URL ending /provapi/submit. Provenance can be specified either as a file upload, via a url or by including the statements with in the submission. The request must be encoded as multipart/form-data. The request should consist of fields one selected from "Content method" and one selected "Request type" from the following fields:

Content specification Field Value Example
- File upload file file upload data ...
- Specify URL url url of the resource http://www.google.com/
- Inline Statements statements body of statements entity(a)
type the type of the statements: ttl,rdf/xml,provn,xml prov
Request type Field Value Comment
- Validation validate Validate Request a validation
- Translation translate json Choose one of these
translate xml
translate provn
translate turtle
translate trig
translate svg

Response

On successful acceptance of the provenance the service will redirect (via HTTP 303 See Other) to appropriate resources.

Validation

The service redirects to a validation resource. You must specify an Accept: header to obtain the validation report in the appropriate format (For HTML: text/html, For XML: application/xml or text/xml). For example:

Request: POST /provapi/submit
Response: 303 /provapi/graph1582655949156048026/validation

Request: GET /provapi/graph1582655949156048026/validation
         Accept: application/xml
Response: 303 /provapi/graph1582655949156048026/validation.xml

Request: GET /provapi/graph1582655949156048026/validation.xml
Response: 200 <validation report in xml>

Translation

For translation, it is possible to negotiate the output format via the HTTP Accept: header, instead of indicating the type as a field in the POST request. The service supports the following mimetypes:

Mimetype Type
text/vnd.graphviz Graph in GraphViz dot format
image/jpeg Graph rendered as a JPEG image
application/pdf Graph rendered in a PDF
image/svg+xml Graph rendered in SVG
application/json PROV-JSON serialization
text/provenance-notation PROV-N
application/rdf+xml PROV-O via RDF encoded in XML
application/x-trig PROV-O in TriG
text/turtle PROV-O in Turtle
text/xml PROV-XML

Example Interaction

Request: POST /provapi/submit
         Accept: application/json
Response: 303 /provapi/graph1582655949156048026/translate

Request: GET /provapi/graph1582655949156048026/translate
         Accept: application/json
Response: 303 /provapi/graph1582655949156048026/translate/json

Request: GET /provapi/graph1582655949156048026/translate/json
Response: 200  <json encoded PROV>

JavaScript API

A JavaScript API is provided. Include the api.js in in the <head> of your HTML document. The API relies on jQuery, so include this also. In this example, we use Google's CDN to provide jQuery.

	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
	<script src="api.js"></script>

Instantiate a new Validator object:

	var validator = new ProvService("url to validator");

The Validator object provides two methods:

Request Type Method Call
Validation validate(input, callback, data_only)
Translation translate(input, mimetype, callback, data_only)

Content specification ("input") is an object:

Type Field
URL url URL to resource
Inline statements Provenance statements
type the type of the statements: ttl,rdf/xml,provn,xml

The callback argument is the function to call once the validation or translation is completed. This is a jQuery.ajax callback (the always variant) - see jQuery documentation. Alternatively, if data_only is true then the parameter passed to the callback is the actual response data after jQuery's best efforts at converting it to a native format.

Examples

	validator.validate(
	    {'url': 'http://www.w3.org/2011/prov/provenance/prov-dm'},
	    function(jqXHR) { alert("Validator responded"); }
	    );
	validator.translate(
	    {'statements': 'entity(a)', 'type': 'provn'},
	    "application/json",
	    function(jqXHR) { alert("Validator responded with: "+jqXHR.reponseText); }
	    );

See the code in action: api test.