Provenance Query API Functional Specification

This page defines the functional specification for the provenance query interface, which should provide all information about how to express provenance queries and process their results. To understand the goal of the interface and the concepts referred to, please refer to the "Architecture for Provenance Systems" document. To be specific enough to use, this functional specification assumes that the p-assertions will be searched over using XPath (this level of technical detail is not covered in the Architecture document).

In the XML schemas shown on this page, the prefix "pq:" refers to the namespace "http://www.pasoa.org/schemas/version023/pquery/ProvenanceQuery.xsd" and the prefix "ps:" refers to the namespace "http://www.pasoa.org/schemas/version023/PStruct.xsd". Both schemas are attached at the bottom of this page and included in the software distribution. All the schemas shown below are taken from this one XML Schema file.

Finally, we have to assume an adequate form of data accessor: one which is comparable and can be derived from the data item to which the accessor should point. For this, we suggest using SingleNodeXPath.

Provenance Query Interface

The provenance query interface is defined by this WSDL document. It defines a single operation, ProvenanceQuery, taking a pq:provenanceQuery element as input (the provenance query request), and returning a pq:provenanceQueryResult as output (the provenance query results).

A provenance query request is made up of the following information, the XML schema is shown below.

• Query Data Handle: A search over the contents of a provenance store which will find the record of an entity at a given instant that the querying actor wishes to find the provenance of.
• Relationship Target Filter: Criteria by which the querying actor specifies whether any given entity in the process documentation, and its provenance, should be included in the query results. By this mechanism, the querying actor can scope the provenance query results.

Query Data Handles

In order for a querying actor to ask provenance stores the question "What is the provenance of entity E at instant T?", the actor must identify the entity in a way that the provenance stores can interpret. The identification used is called a query data handle. From the application perspective, a query data handle identifies an application entity at a given instant. From the provenance store perspective, a query data handle identifies a search for p-assertion data items within the process documentation.

The schema for a query data handle is shown below. The search element specifies a search, in the chosen search language, over the p-structure for data items within p-assertions asserted about given instants. The documentLanguageMappings specify how p-assertion contents are mapped to the document language required by the search. The pStructureReference specifies whether the search is over the contents of the queried provenance store, the results of a provenance query or the transitive closure of a relation over a p-structure.

XPath Searches

To specify a search using XPath, provide the path expression and prefix-to-namespace mappings using the schema below.

P-Structure Reference

The p-structure reference is given using the schema below.

Relationship Target Filters

The set of process documentation that ultimately has some causal influence on the entity identified by a query data handle could be vast, and most of it irrelevant to a querying actor for any one purpose. Therefore, we need to allow the querying actor to specify the scope of the provenance query, i.e. a definition of what documentation is relevant enough to be part of the results. This is the purpose of the relationship target filter.

The schema of the relationship target filter is shown below. The check element specifies a function, using a chosen search language, over relationship target returning true or false, and can be an XPath search as defined above. The documentLanguageMappings specify how p-assertion contents are mapped to the document language required by the search.

Relationship Target

A relationship target is the full set of information about a p-assertion data item that is the subject or object of a relationship p-assertion. A relationship target filter is a search over a relationship target. The schema for a relationship target is shown below, each sub-element being defined as follows.

• The interaction key, including source and sink, of the interaction in which the data item was exchanged or part of an actor's state.
• Whether the actor that asserted the data item was the sender or receiver in the interaction.
• The local p-assertion ID of the p-assertion in which the data item is contained.
• The parameter name of this data item in the relationship p-assertion.
• The address of the provenance store in which the p-assertion is documented.
• The location of the data item within the p-assertion, given by the data accessor.
• The name of the relation of which this target is a subject or object.
• The identity of the actor that asserted the data item.
• The content of the interaction or actor state p-assertion containing the data item.

Provenance Query Results

The response to a provenance query is a representation of the provenance of an entity at a given instant, i.e. the one specified by the query data handle. Provenance query results are comprised of the following, the schema is shown below:

• Start: The p-assertion data key(s) to the process documentation of the entity for which the provenance was found, i.e. the key(s) for the p-assertion data item(s) found by resolving the query data handle.
• Full Relationships: Relationships between data items determined to be in scope by the relationship target filter.

The schema for the subjects of full relationships is shown below, and the model for objects is identical.

-- SimonMiles - 13 Mar 2006
to top