Pingback message validator

About the Validator

This pingbacks message validator has been established to help people validate PROV-AQ and PROMS 'pingback' messages. These messages are used to communicate provenance information between provenance mangament systems.

The code for this system is at https://github.com/nicholascar/proms-pingbacks-validator.

About pingback messages

Pingback messages are HTTP messages from a client to a server informing the server about provenance information for a target resource that the recieving pingbacks endpoint has been set up to process.

PROV-AQ messages are as per the PROV-AQ W3C technical note (hopefully soon a W3C recommendation) in the PROV Data Model family of documents. PROMS messages are bundles (prov:Bundle) of provenance information that follow certain rules that one provenance system may send to another. PROMS messages were formulated since the authors of the PROMS Server wanted the ability to 'pingback' provenance information but PROV-AQ does not provide for this.

See below in the 'Pingback messages description' section, after the description of 'How to use the Validator' for fuller descriptions of PROV-AQ and PROMS messages.

How to use the Validator

Form input

This validator contains a web form you can use to send pingback messages to the validation system, see . All of the various message type options are present on the form page and results, as per the PROV-AQ or the PROMS specs are displayed after message processing on screen.

To use the form input method, you will need to formulate your pingback message body first and then enter it into the form.

Script/command line input

  1. formulate your message
  2. send the message, via an HTTP POST request, to one of the validator endpoints
  3. review the validator results
    • success/error messages are returned as HTTP codes and response body text, as per the PROV-AQ & PROMS specs.

Validator Endpoints

Pingback messages description

PROV-AQ messages

According to the PROV-AQ specification (Section 5) a pingbacks message is :

Example 1 - a basic pingbacks message

POST http://example.com/target-resource/pingback HTTP/1.1
Content-Type: text/uri-list

http://something.com/some-provenance.rdf
http://somethingelse.com/provenance?_format=ttl

Further Links

A basic prinbacks message contains just a list of URIs indicating where provenance information for the target resource is to be found.

"Further Links" can be specified that:

Both these types of further links are indicated by adding the URIs of these links to the message body and adding descriptive HTTP Link headers to the pingbacks message as follows:

Example 2 - a pingbacks message with a query service link for the target resource

POST http://example.com/target-resource/pingback HTTP/1.1
Link: <http://other.org/some-query-service>;
rel="http://www.w3.org/ns/prov#has_provenance";
anchor="http://example.com/target-resource"
Content-Type: text/uri-list
Content-Length: 0
	

Note that, in this example, no has_provenance links have been given so that this message only includes a single has_query_service link in the Link header. The Content-Length header has been set to zero to ensure the server understands that there is no body content. There could have been in which case the Content-Length header would not have been set.

Example 3 - a pingbacks message with a has_provenance link for resources other than the target resource

POST http://example.com/target-resource/pingback HTTP/1.1
Link: <http://other.org/provenance-resource.rdf>;
rel="http://www.w3.org/ns/prov#has_provenance";
anchor="http://example.com/other-resource"
Content-Type: text/uri-list

http://something.com/some-provenance.rdf
http://somethingelse.com/provenance?_format=ttl
http://other.org/provenance-resource.rdf
	

Note that the new link to the provenance resource in the Link header for the non-target resource, http://other.org/provenance-resource.rdf, may or may not be also given in the in the message body. In this case it is. It depends on whether the provenance resource is relecant to both the target resource and the non-terget resources, or both.

has_query_service links may be specified for non-target resources too.

PROV-AQ responses

Valid messages recieve a response HTTP status code of 204 'No Content' and no response body. Invalid messages receive an HTTP 400 'Bad Command' status code and one or more detailed error messages in the response body as plain text.

PROMS messages

These messages are RDF documents that must be sent with one of the following Content-Type headers:

Once successfully parsed, the RDF document is checked according to the following rules:

NameDescription
Rule 1PROV-OThe RDF document must be a valid PROV-O document as per the PROV constraints.
(not implemented yet)
Rule 2Pingback PropertyAt least one prov:Entity (or subclass) must declare a prov:pingback property with the pingback target URI as its range value (object). In this validator's case, an Entity must have a property pointing to <http://promsns.org/pingbacks/validator/validator-proms>
Rule 3Entities UsedAll Entities with pingback properties declared, as per Rule 2, must only be used or otherwise consumed by Activities, not wasGeneratedBy an Activity or indicated as being wasDerivedFrom any other Entity. Anything reported as having been generated in new provenance information cannot already have pre-existing provenance for a pingbacked message payload to be added to.

PROMS responses

Valid messages recieve a response HTTP status code of 201 'Created' and a resonse body, in plain text, of the phrase "Created {COUNT} triples." reflecting the number of triples inserted into the receiving triplestore. No actual insert takes place in the validator. Invalid messages receive an HTTP 400 'Bad Command' status code and one or more detailed error messages in the response body as plain text.