OriginTrail
Search…
Example flow: Publishing Product Dataset, Resolving, Searching on the DKG and Querying via SPARQL
This page intends to introduce a basic flow of:
  • publishing a dataset to the DKG
  • resolving a dataset to the DKG
  • searching for it via the search API
  • querying using SPARQL
More instructions will be provided through the documentation in the following updates.

How to publishing product dataset on DKG?

Dataset Description
The dataset used in this tutorial is maintained by jsonld.com can be found here https://jsonld.com/product/
It follows Schema.org as standard and contains an object of type Product with its description, identifier, brand, rating and other details. An extensive documentation for Product class can be found here https://schema.org/Product. The sample dataset values can be referred below:
1
{
2
"@context": "https://schema.org/",
3
"@type": "Product",
4
"name": "Executive Anvil",
5
"image": "http://www.example.com/anvil_executive.jpg",
6
"description": "Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height.",
7
"mpn": "925872",
8
"brand": {
9
"@type": "Thing",
10
"name": "ACME"
11
},
12
"aggregateRating": {
13
"@type": "AggregateRating",
14
"ratingValue": "4.4",
15
"reviewCount": "89"
16
},
17
"offers": {
18
"@type": "Offer",
19
"priceCurrency": "USD",
20
"price": "119.99",
21
"priceValidUntil": "2020-11-05",
22
"itemCondition": "http://schema.org/UsedCondition",
23
"availability": "http://schema.org/InStock",
24
"seller": {
25
"@type": "Organization",
26
"name": "Executive Objects"
27
}
28
}
29
}
Copied!
Save the above dataset as Product.json to be passed in API.

Publishing via Publish API

Here we are going to publish the above Product dataset with the Publish API:
1
//API call
2
POST http://NODE_IP:PORT/publish
3
​
4
//pass Product.json path in files variables
5
payload= {
6
'assets': '["0x123456789123456789123456789"]',
7
'keywords': '["Product", "Executive Objects", "ACME"]',
8
'visibility': 'true'
9
}
10
​
11
files=[
12
('file',('Product.json',open('{LocalPATH}/Product.json','rb'),'application/json'))
13
]
Copied!

Getting Assertion_ID after successful publish operation

On successful publish, the response will generate a handler_id which can be further used as a parameter for below API:
NOTE: The pattern of using handlers for Resolve, Search and Query API remains the same.
1
POST http://NODE_IP:PORT/publish/result/${handler_id}
Copied!
As a result, user will get the following response for publishing the dataset successfully.
1
{
2
"status": "COMPLETED",
3
"data": {
4
"id": "f44199fdc034a105a538e5f8f86fb0418b5ac6b80a537176d55e900ce53720b9",
5
"rootHash": "f29afc26528610294a426015a30fdac7cefaf32f6002cf8f934bce14e951566a",
6
"signature": "0x44694dc8f3ea5abcf0054a5437e517eefad6aab7e9aaf881227dcd253237a7961e9fb11a7d99af9e7baba885626f70ead66c3e3b9d57595ff57a263b0560ac101c",
7
"metadata": {
8
"type": "Person",
9
"timestamp": "2021-12-24T10:20:12.881Z",
10
"issuer": "0xbd084ab97c704fe4a6d620cb7c30c0be0366646f",
11
"visibility": true,
12
"dataHash": "c8817ca24382818180a978fb1e628904ea4abd0a9d526ad2ca0aa9ad552b4283"
13
}
14
}
15
}
Copied!
The assertion_id(id) above can be used for Resolve in next section.

How to resolve an assertion on the DKG?

Data are persisted on the network by publishing on the DKG. Data are published as assertions that are immutable and verifiable, which could be resolved using assertion ID. Assertion ID is signed hash of published triples which is calculated during the publish.

Resolving via Resolve API

In this tutorial, we are going to resolve the above Product assertion with the Resolve API using /resolve and /resolve/result API routes:
1
GET http://NODE_IP:PORT/resolve?ids={assertion_id}
Copied!
The result of above is the following:
1
​
2
{
3
"metadata": {
4
"dataHash": "ed13153fa4090eceedf6c1dd1aa030ec45ab75c2f9510c64a2014f1c6424e7dd",
5
"issuer": "0xbd084ab97c704fe4a6d620cb7c30c0be0366646f",
6
"timestamp": "2021-12-27T16:06:57.912Z",
7
"type": "Product",
8
"visibility": true
9
},
10
"blockchain": {
11
"name": "polygon::testnet",
12
"transactionHash": "0x16dbb9117d566a9ecc62dabb3175782a425e466b4abfa138986f357cacc9909f"
13
},
14
"assets": [
15
"f7fb9c597ec04c1a7a6c1b03f5ef365ac7b47416b23e4c0772195175258266b8"
16
],
17
"keywords": [
18
"Product",
19
"0x1242356452",
20
"executive anvil"
21
],
22
"signature": "0xbe37c15aa21835b9fe50b5225cfb61cd8ab3f06374705a91f5a5989105d2d2ec151c8bbb5d0f07c8508d37c77a15ac08456342d156ae52ced4520c15cb94eee91c",
23
"rootHash": "45f04483daac38828d634d404e1a12d60d7b4749813edea7fd8b1701a725f37e",
24
"id": "6b02bc68a44c255c0738b94a72a41ae2c0959e7e6a53554f90ec75ed6d7921de",
25
"data": {
26
"@context": "https://www.schema.org/",
27
"@graph": [
28
{
29
"aggregateRating": {
30
"id": "_:b1",
31
"ratingValue": "4.4",
32
"reviewCount": "89",
33
"type": "AggregateRating"
34
},
35
"brand": {
36
"id": "_:b2",
37
"name": "ACME",
38
"type": "Thing"
39
},
40
"description": "Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height.",
41
"image": "http://www.example.com/anvil_executive.jpg",
42
"mpn": "925872",
43
"name": "Executive Anvil",
44
"offers": {
45
"availability": "http://schema.org/InStock",
46
"id": "_:b3",
47
"itemCondition": "http://schema.org/UsedCondition",
48
"price": "119.99",
49
"priceCurrency": "USD",
50
"priceValidUntil": "2020-11-05",
51
"seller": {
52
"id": "_:b4",
53
"name": "Executive Objects",
54
"type": "Organization"
55
},
56
"type": "Offer"
57
},
58
"type": "Product"
59
},
60
{
61
"id": "_:b1",
62
"ratingValue": "4.4",
63
"reviewCount": "89",
64
"type": "AggregateRating"
65
},
66
{
67
"id": "_:b2",
68
"name": "ACME",
69
"type": "Thing"
70
},
71
{
72
"availability": "http://schema.org/InStock",
73
"id": "_:b3",
74
"itemCondition": "http://schema.org/UsedCondition",
75
"price": "119.99",
76
"priceCurrency": "USD",
77
"priceValidUntil": "2020-11-05",
78
"seller": {
79
"id": "_:b4",
80
"name": "Executive Objects",
81
"type": "Organization"
82
},
83
"type": "Offer"
84
},
85
{
86
"id": "_:b4",
87
"name": "Executive Objects",
88
"type": "Organization"
89
}
90
]
91
}
92
}
Copied!
Data integrity could be verified by calculating sha256(sha256(metadata)sha256(data)).

How to search for an entity or an assertion on the DKG?

DKG can be searched by keywords for related assets and assertions. Search result consists of elements listed by score and issuer.

Searching for an entity via Search API

In this tutorial, we are going to search the above Product entity using /entities:search and /entities:search/result API routes:
1
//Search for ExecutiveAnvil
2
curl --location --request GET 'http://NODE_IP:PORT/entities:search?prefix=true&limit=20&query=ExecutiveAnvil'
Copied!
The result of Search API route is the following:
1
{
2
"@context": {
3
"@vocab": "http://schema.org/",
4
"goog": "http://schema.googleapis.com/",
5
"resultScore": "goog:resultScore",
6
"detailedDescription": "goog:detailedDescription",
7
"EntitySearchResult": "goog:EntitySearchResult",
8
"kg": "http://g.co/kg"
9
},
10
"@type": "ItemList",
11
"itemListElement": [
12
{
13
"@type": "EntitySearchResult",
14
"result": {
15
"@id": "f7fb9c597ec04c1a7a6c1b03f5ef365ac7b47416b23e4c0772195175258266b8",
16
"@type": "PRODUCT",
17
"@context": "https://www.schema.org/",
18
"@graph": [
19
{
20
"type": "Product",
21
"aggregateRating": {
22
"id": "_:b1",
23
"type": "AggregateRating",
24
"ratingValue": "4.4",
25
"reviewCount": "89"
26
},
27
"brand": {
28
"id": "_:b2",
29
"type": "Thing",
30
"name": "ACME"
31
},
32
"description": "Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height.",
33
"image": "http://www.example.com/anvil_executive.jpg",
34
"mpn": "925872",
35
"name": "Executive Anvil",
36
"offers": {
37
"id": "_:b3",
38
"type": "Offer",
39
"availability": "http://schema.org/InStock",
40
"itemCondition": "http://schema.org/UsedCondition",
41
"price": "119.99",
42
"priceCurrency": "USD",
43
"priceValidUntil": "2020-11-05",
44
"seller": {
45
"id": "_:b4",
46
"type": "Organization",
47
"name": "Executive Objects"
48
}
49
}
50
},
51
{
52
"id": "_:b1",
53
"type": "AggregateRating",
54
"ratingValue": "4.4",
55
"reviewCount": "89"
56
},
57
{
58
"id": "_:b2",
59
"type": "Thing",
60
"name": "ACME"
61
},
62
{
63
"id": "_:b3",
64
"type": "Offer",
65
"availability": "http://schema.org/InStock",
66
"itemCondition": "http://schema.org/UsedCondition",
67
"price": "119.99",
68
"priceCurrency": "USD",
69
"priceValidUntil": "2020-11-05",
70
"seller": {
71
"id": "_:b4",
72
"type": "Organization",
73
"name": "Executive Objects"
74
}
75
},
76
{
77
"id": "_:b4",
78
"type": "Organization",
79
"name": "Executive Objects"
80
}
81
]
82
},
83
"issuers": [
84
"0xbd084ab97c704fe4a6d620cb7c30c0be0366646f"
85
],
86
"assertions": [
87
"6b02bc68a44c255c0738b94a72a41ae2c0959e7e6a53554f90ec75ed6d7921de"
88
],
89
"nodes": [
90
"QmdD6AuWRoVpAjkxEtBgeUDUBaddNT3SD2cZo8sMV5CMn6"
91
],
92
"resultScore": 0
93
}
94
]
95
}
Copied!

Searching for an assertion via Search API

In this tutorial, we are going to search the above Product entity using /entities:search and /entities:search/result API routes:
1
curl --location --request GET 'http://127.0.0.1:8901/assertions:search?prefix=true&limit=20&query=ExecutiveAnvil'
Copied!
The result of Search API route is the following:
1
{
2
"@context": {
3
"@vocab": "http://schema.org/",
4
"goog": "http://schema.googleapis.com/",
5
"resultScore": "goog:resultScore",
6
"detailedDescription": "goog:detailedDescription",
7
"EntitySearchResult": "goog:EntitySearchResult",
8
"kg": "http://g.co/kg"
9
},
10
"@type": "ItemList",
11
"itemListElement": [
12
{
13
"@type": "AssertionSearchResult",
14
"result": {
15
"@id": "6b02bc68a44c255c0738b94a72a41ae2c0959e7e6a53554f90ec75ed6d7921de",
16
"metadata": {
17
"issuer": "0xbd084ab97c704fe4a6d620cb7c30c0be0366646f",
18
"type": "Product",
19
"timestamp": "2021-12-27T16:06:57.912Z",
20
"visibility": true,
21
"dataHash": "ed13153fa4090eceedf6c1dd1aa030ec45ab75c2f9510c64a2014f1c6424e7dd"
22
},
23
"signature": "0xbe37c15aa21835b9fe50b5225cfb61cd8ab3f06374705a91f5a5989105d2d2ec151c8bbb5d0f07c8508d37c77a15ac08456342d156ae52ced4520c15cb94eee91c",
24
"rootHash": "45f04483daac38828d634d404e1a12d60d7b4749813edea7fd8b1701a725f37e"
25
},
26
"nodes": [
27
"QmdD6AuWRoVpAjkxEtBgeUDUBaddNT3SD2cZo8sMV5CMn6"
28
],
29
"resultScore": 0
30
}
31
]
32
}
Copied!

How to run SPARQL queries on DKG?

The DKG querying entails both data discovery and graph querying. Therefore OriginTrail implements a set of protocols for discovery and exchange which cover a wide array of possible scenarios. This section covers querying through SPARQL constrict.

SPARQL query

Querying the DKG is done using the SPARQL query API. It is used to look up all datasets containing a specific identifier/Value.
The SPARQL Construct query helps to get the response as a RDF sub-graph. In case users are interested to create their own application, this returned portable sub-graph contains all of the information needed to build a section of application. Then instead of many select queries to the full database, these queries can be run over the much smaller sub-graph returned by the construct query.
Using the API with a sample construct query (Dataset having seller with name 'Executive Objects')
1
POST http://NODE_IP:PORT/query?type=construct
2
​
3
//provide all the connected properties and values for an object having sellername
4
//'Executive Objects'
5
​
6
payload=
7
{
8
'query': 'PREFIX schema: <http://schema.org/>
9
construct { ?s ?p ?o}
10
WHERE {
11
GRAPH ?g {
12
?s ?p ?o .
13
?s schema:offers / schema:seller/ schema:name "Executive Objects" .
14
}
15
}'
16
}
Copied!
The returned responses contain query_id which can be used to fetch responses from network query.
To view responses call the query response API, as a parameter use query_id returned from network query API call.
1
GET http://NODE_IP:PORT/query/result/{query_id}
Copied!
The returned responses contain an array of all connected nodes for returned dataset which contain objects whose identifiers(or value) fit the given query.
1
{
2
"status": "COMPLETED",
3
"data": {
4
"response": [
5
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Product> .",
6
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://schema.org/description> \"Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height.\" .",
7
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://schema.org/name> \"Executive Anvil\" .",
8
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://schema.org/aggregateRating> _:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n4 .",
9
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://schema.org/brand> _:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n2 .",
10
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://schema.org/image> <http://www.example.com/anvil_executive.jpg> .",
11
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://schema.org/mpn> \"925872\" .",
12
"_:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n0 <http://schema.org/offers> _:genid2dfbcb2d181a59423e9a3ec6cf297826782dc14n3 .",
13
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Product> .",
14
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://schema.org/description> \"Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height.\" .",
15
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://schema.org/name> \"Executive Anvil\" .",
16
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://schema.org/aggregateRating> _:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n4 .",
17
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://schema.org/brand> _:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n2 .",
18
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://schema.org/image> <http://www.example.com/anvil_executive.jpg> .",
19
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://schema.org/mpn> \"925872\" .",
20
"_:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n0 <http://schema.org/offers> _:genid2d7b11008feb8e454cafcdb8b6d5666d722dc14n3 .",
21
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Product> .",
22
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://schema.org/description> \"Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height.\" .",
23
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://schema.org/name> \"Executive Anvil\" .",
24
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://schema.org/aggregateRating> _:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n4 .",
25
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://schema.org/brand> _:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n2 .",
26
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://schema.org/image> <http://www.example.com/anvil_executive.jpg> .",
27
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://schema.org/mpn> \"925872\" .",
28
"_:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n0 <http://schema.org/offers> _:genid2d35b7d44ec4b6485aacfbe6cb27db3eca2dc14n3 ."
29
]
30
}
31
}
Copied!
​

​

Last modified 17d ago