The Relations Resource

A PROV relation is either a binary relation between a subject and object, or a ternary relation between a subject, object, and secondary object. In the latter case the secondary object is always optional.

JSON representing ternary relations will always have a secondaryObject property, but secondaryObject.provId (or secondaryObject.provIdSearchResults in the case of relationDetail) will be missing if the relation instance does not actually have a secondary object assigned.

The current storage model treats a relation as a relation between PROV identifiers rather than types. This is why relationDetail contains provIdSearchResults rather than simple references to types.

GET /relations

Get a list of user's PROV relations, e.g., Derivations, Generations, ...

Relations are returned as a relationPage. A user may have created more than one page of relations. See the pageToken query parameter for details. See /documents/{docId}/relations for info on how to restrict to relations declared in a given document.

Request

Query Parameters

pageToken (optional)

If omitted, the first page of relations will be returned. If the user has created more than one page worth of relations the response will contain a nextPage property. This value can be passed as pageToken to get the next page of results. The final page will have no nextPage property.

creatorId (optional)

An admin can includes this in the query string to get another user's relations.

Header Parameters

authentication headers

Accept

application/json

Response

Body

{
    "relationPage": {
        "pageToken": "0",
        "nextToken": "10",
        "relations": [
            {
                "id": "1048593",
                "name": "ATTRIBUTION",
                "subject": {
                    "name": "entity",
                    "provId": "http://www.example.org/chart1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                }
            },
            {
                "id": "1048611",
                "name": "START",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/correct1"
                },
                "object": {
                    "name": "trigger"
                },
                "secondaryObject": {
                    "name": "starter"
                }
            },
            {
                "id": "1048617",
                "name": "SPECIALIZATION",
                "subject": {
                    "name": "specificEntity",
                    "provId": "http://www.example.org/articleV1"
                },
                "object": {
                    "name": "generalEntity",
                    "provId": "http://www.example.org/article"
                }
            },
            {
                "id": "1048619",
                "name": "SPECIALIZATION",
                "subject": {
                    "name": "specificEntity",
                    "provId": "http://www.example.org/articleV2"
                },
                "object": {
                    "name": "generalEntity",
                    "provId": "http://www.example.org/article"
                }
            },
            {
                "id": "1048591",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/compose1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                },
                "secondaryObject": {
                    "name": "plan"
                }
            },
            {
                "id": "1048592",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/illustrate1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                },
                "secondaryObject": {
                    "name": "plan"
                }
            },
            {
                "id": "1048597",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/compose1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                },
                "secondaryObject": {
                    "name": "plan"
                }
            },
            {
                "id": "1048607",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/correct1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/edith"
                },
                "secondaryObject": {
                    "name": "plan",
                    "provId": "http://www.example.org/instructions"
                }
            },
            {
                "id": "1048586",
                "name": "GENERATION",
                "subject": {
                    "name": "entity",
                    "provId": "http://www.example.org/composition1"
                },
                "object": {
                    "name": "activity",
                    "provId": "http://www.example.org/compose1"
                }
            },
            {
                "id": "1048588",
                "name": "GENERATION",
                "subject": {
                    "name": "entity",
                    "provId": "http://www.example.org/chart1"
                },
                "object": {
                    "name": "activity",
                    "provId": "http://www.example.org/illustrate1"
                }
            }
        ]
    }
}

GET /relations/{relationId}

Get the details of a relation. This includes attributes, PROV identifier search results for members of the relation, and the documents in which the relation is declared.

Request

Path Parameters

relationId

The relation.id of the desired relation.

Query Parameters

name

The relation.name of the desired relation. For example, GENERATION.

Header Parameters

authentication headers

Accept

application/json

Response

Body

{
    "relationDetail": {
        "id": "90720",
        "name": "DERIVATION",
        "subject": {
            "name": "generatedEntity",
            "provIdSearchResults": {
                "provId": "http://example.org/quoteInBlogEntry-20130326",
                "types": {
                    "ENTITY": [
                        "90729",
                        "148614"
                    ]
                }
            }
        },
        "object": {
            "name": "usedEntity",
            "provIdSearchResults": {
                "provId": "http://www.example.org/article",
                "types": {
                    "ENTITY": [
                        "90711",
                        "108576"
                    ]
                }
            }
        },
        "secondaryObject": {
            "name": "activity"
        },
        "attributes": [
            {
                "id": "58747",
                "name": "http://www.w3.org/ns/prov#type",
                "value": "prov:Quotation"
            }
        ],
        "declaringDocuments": [
            {
                "id": "81",
                "version": 0,
                "name": "upload895",
                "creator": "user123",
                "creatorId": 21,
                "createTime": "2016-09-22T15:33:59Z"
            }
        ]
    }
}