Live demo: SKG-IF APIs for ORKG and Wikidata#
HERITRACE is a software for semantic data editing, presented in a journal article. The article metadata is available on ORKG, while the software metadata is available on Wikidata.
This notebook demonstrates how RAMOSE retrieves both types of information from different data sources and returns them in a single, SKG-IF compatible schema.
To run it interactively, click Open in Colab in the top bar.
!pip install -q -U ramose
from importlib.metadata import version
print("ramose", version("ramose"))
ramose 2.8.0
from urllib.request import urlretrieve
urlretrieve(
"https://raw.githubusercontent.com/opencitations/ramose/master/docs/orkg_skgif.hf",
"orkg_skgif.hf",
)
urlretrieve(
"https://raw.githubusercontent.com/opencitations/ramose/master/docs/wikidata_skgif.hf",
"wikidata_skgif.hf",
)
Query HERITRACE as a journal article (ORKG)#
import json
from ramose import APIManager
api_manager = APIManager(["orkg_skgif.hf"])
op = api_manager.get_op("/skg-if-orkg/v1/products/http://orkg.org/orkg/resource/R1637585")
status, body, content_type, headers = op.exec()
print(json.dumps(json.loads(body), indent=2))
{
"@context": [
"https://w3id.org/skg-if/context/1.1.0/skg-if.json",
"https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
{
"@base": "https://w3id.org/skg-if/sandbox/acme/"
}
],
"meta": {
"local_identifier": "https://w3id.org/skg-if/sandbox/orkg/skg-if-orkg/v1/products/http://orkg.org/orkg/resource/R1637585",
"entity_type": "single_entity"
},
"@graph": [
{
"local_identifier": "http://orkg.org/orkg/resource/R1637585",
"product_type": "literature",
"titles": {
"none": [
"HERITRACE: A User-Friendly Semantic Data Editor with Change Tracking and Provenance Management for Cultural Heritage Institutions"
]
},
"identifiers": [
{
"value": "10.6092/ISSN.2532-8816/21218",
"scheme": "doi"
}
],
"contributions": [
{
"role": "author",
"by": {
"name": "Arcangelo Massari",
"entity_type": "agent",
"identifiers": [
{
"value": "0000-0002-8420-0696",
"scheme": "orcid"
}
],
"local_identifier": "http://orkg.org/orkg/resource/R1637559"
},
"rank": 1
},
{
"role": "author",
"by": {
"name": "Silvio Peroni",
"entity_type": "agent",
"identifiers": [
{
"value": "0000-0003-0530-4305",
"scheme": "orcid"
}
],
"local_identifier": "http://orkg.org/orkg/resource/R9566"
},
"rank": 2
}
],
"topics": [
{
"term": {
"local_identifier": "http://orkg.org/orkg/resource/R141823",
"entity_type": "topic",
"labels": {
"none": "Semantic Web"
}
}
}
],
"manifestations": [
{
"dates": {
"publication": [
"2025-07-01T00:00:00"
]
},
"biblio": {
"in": {
"name": "Umanistica Digitale",
"entity_type": "venue",
"local_identifier": "http://orkg.org/orkg/resource/R585576",
"identifiers": [
{
"value": "http://orkg.org/orkg/resource/R1640846",
"scheme": "issn"
}
]
}
}
}
],
"entity_type": "product"
}
]
}
Query HERITRACE as a software (Wikidata)#
wikidata_manager = APIManager(["wikidata_skgif.hf"])
op = wikidata_manager.get_op("/skg-if-wikidata/v1/products/http://www.wikidata.org/entity/Q139571902")
status, body, content_type, headers = op.exec()
print(json.dumps(json.loads(body), indent=2))
{
"@context": [
"https://w3id.org/skg-if/context/1.1.0/skg-if.json",
"https://w3id.org/skg-if/context/1.0.0/skg-if-api.json",
{
"@base": "https://w3id.org/skg-if/sandbox/acme/"
}
],
"meta": {
"local_identifier": "https://w3id.org/skg-if/sandbox/wikidata/skg-if-wikidata/v1/products/http://www.wikidata.org/entity/Q139571902",
"entity_type": "single_entity"
},
"@graph": [
{
"local_identifier": "http://www.wikidata.org/entity/Q139571902",
"product_type": "research software",
"titles": {
"en": [
"HERITRACE"
]
},
"identifiers": [
{
"value": "https://archive.softwareheritage.org/swh:1:snp:1d58ffefc1133ebc84a7aebb75cb14c3521e98b4",
"scheme": "url"
},
{
"value": "https://zenodo.org/record/11198005",
"scheme": "url"
}
],
"contributions": [
{
"role": "author",
"by": {
"name": "Arcangelo Massari",
"entity_type": "agent",
"identifiers": [
{
"value": "0000-0002-8420-0696",
"scheme": "orcid"
}
],
"local_identifier": "http://www.wikidata.org/entity/Q113011042"
},
"rank": 1
}
],
"manifestations": [
{
"dates": {
"publication": [
"2026-02-14T00:00:00"
]
},
"licence": "http://www.wikidata.org/entity/Q386474",
"version": "3.0.0"
}
],
"entity_type": "product"
}
]
}
Generated HTML documentation#
RAMOSE also generates interactive API documentation from the same spec file. When RAMOSE runs as a web server (ramose -s spec.hf -w 127.0.0.1:8080), it serves this page at each API’s base path (for example /skg-if-orkg/v1).
import html
from IPython.display import HTML
from ramose import HTMLDocumentationHandler
doc_handler = HTMLDocumentationHandler(api_manager)
_, html_content = doc_handler.get_documentation()
HTML(f'<iframe srcdoc="{html.escape(html_content, quote=True)}" width="100%" height="600" style="border:0"></iframe>')
/home/runner/work/ramose/ramose/.venv/lib/python3.12/site-packages/IPython/core/display.py:447: UserWarning: Consider using IPython.display.IFrame instead
warnings.warn("Consider using IPython.display.IFrame instead")
Generated OpenAPI specification#
RAMOSE generates an OpenAPI 3.2 specification from the same spec file. When RAMOSE runs as a web server (ramose -s spec.hf -w 127.0.0.1:8080), it serves the spec at each API’s openapi.yaml (for example /skg-if-orkg/v1/openapi.yaml).
from ramose import OpenAPIDocumentationHandler
openapi_handler = OpenAPIDocumentationHandler(api_manager)
_, openapi_yaml = openapi_handler.get_documentation()
print(openapi_yaml)
openapi: 3.2.0
info:
title: SKG-IF API for ORKG
version: 0.1.0
description: SKG-IF compliant API exposing ORKG (Open Research Knowledge Graph)
bibliographic data as JSON-LD, following the <a href="https://skg-if.github.io/interoperability-framework/"
target="_blank">Scholarly Knowledge Graph Interoperability Framework specification</a>.
license:
name: This document is licensed with a Creative Commons Attribution 4.0 International
License, while the REST API itself has been created using RAMOSE, the Restful
API Manager Over SPARQL Endpoints, which is licensed with an ISC license.
url: https://creativecommons.org/licenses/by/4.0/legalcode
contact:
email: info@orkg.org
servers:
- url: https://w3id.org/skg-if/sandbox/orkg/skg-if-orkg/v1
components:
schemas:
Error:
type: object
properties:
error:
type: integer
message:
type: string
required:
- error
- message
example:
error: 404
message: 'HTTP status code 404: resource not found'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
paths:
/products/{local_identifier}:
get:
tags:
- SKG-IF API for ORKG
summary: Returns a single research product from ORKG identified by its resource
URI.
description: Returns a single research product from ORKG identified by its resource
URI.
parameters:
- name: local_identifier
in: path
required: true
schema:
type: string
pattern: http://orkg\.org/orkg/resource/R\d+
example: http://orkg.org/orkg/resource/R1637585
responses:
'200':
description: Successful response
content:
application/ld+json:
schema:
type: object
properties:
'@context':
type: array
meta:
type: object
properties:
local_identifier:
type: string
entity_type:
type: string
part_of:
type: object
properties:
local_identifier:
type: string
entity_type:
type: string
total_items:
type: integer
first_page:
type: object
properties:
local_identifier:
type: string
entity_type:
type: string
last_page:
type: object
properties:
local_identifier:
type: string
entity_type:
type: string
'@graph':
type: array
items:
type: object
properties:
local_identifier:
type: string
entity_type:
type: string
product_type:
type: string
titles:
type: object
properties:
none:
type: array
items:
type: string
identifiers:
type: array
items:
type: object
properties:
value:
type: string
scheme:
type: string
contributions:
type: array
items:
type: object
properties:
role:
type: string
by:
type: object
properties:
name:
type: string
entity_type:
type: string
local_identifier:
type: string
identifiers:
type: array
items:
type: object
properties:
value:
type: string
scheme:
type: string
rank:
type: integer
manifestations:
type: array
items:
type: object
properties:
dates:
type: object
properties:
publication:
type: array
items:
type: string
biblio:
type: object
properties:
in:
type: object
properties:
name:
type: string
entity_type:
type: string
local_identifier:
type: string
identifiers:
type: array
items:
type: object
properties:
value:
type: string
scheme:
type: string
topics:
type: array
items:
type: object
properties:
term:
type: object
properties:
local_identifier:
type: string
entity_type:
type: string
labels:
type: object
properties:
none:
type: string
examples:
example:
value:
'@context':
- https://w3id.org/skg-if/context/1.1.0/skg-if.json
- https://w3id.org/skg-if/context/1.0.0/skg-if-api.json
- '@base': https://w3id.org/skg-if/sandbox/acme/
meta:
local_identifier: https://w3id.org/skg-if/sandbox/orkg/skg-if-orkg/v1/products/http://orkg.org/orkg/resource/R1637585?page=1&page_size=1
entity_type: search_result_page
part_of:
local_identifier: https://w3id.org/skg-if/sandbox/orkg/skg-if-orkg/v1/products/http://orkg.org/orkg/resource/R1637585
entity_type: search_result
total_items: 1
first_page:
local_identifier: https://w3id.org/skg-if/sandbox/orkg/skg-if-orkg/v1/products/http://orkg.org/orkg/resource/R1637585?page=1&page_size=1
entity_type: search_result_page
last_page:
local_identifier: https://w3id.org/skg-if/sandbox/orkg/skg-if-orkg/v1/products/http://orkg.org/orkg/resource/R1637585?page=1&page_size=1
entity_type: search_result_page
'@graph':
- local_identifier: http://orkg.org/orkg/resource/R1637585
entity_type: product
product_type: literature
titles:
none:
- 'HERITRACE: A User-Friendly Semantic Data Editor with Change
Tracking and Provenance Management for Cultural Heritage
Institutions'
identifiers:
- value: 10.6092/ISSN.2532-8816/21218
scheme: doi
contributions:
- role: author
by:
name: Arcangelo Massari
entity_type: agent
local_identifier: http://orkg.org/orkg/resource/R1637559
identifiers:
- value: 0000-0002-8420-0696
scheme: orcid
rank: 1
- role: author
by:
name: Silvio Peroni
entity_type: agent
local_identifier: http://orkg.org/orkg/resource/R9566
identifiers:
- value: 0000-0003-0530-4305
scheme: orcid
rank: 2
manifestations:
- dates:
publication:
- '2025-07-01T00:00:00'
biblio:
in:
name: Umanistica Digitale
entity_type: venue
local_identifier: http://orkg.org/orkg/resource/R585576
identifiers:
- value: 2532-8816
scheme: issn
topics:
- term:
local_identifier: http://orkg.org/orkg/resource/R141823
entity_type: topic
labels:
none: Semantic Web
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Interactive Swagger UI#
The same specification renders as interactive Swagger UI. When RAMOSE runs as a web server (ramose -s spec.hf -w 127.0.0.1:8080), it serves Swagger UI at /docs.
import html
from IPython.display import HTML
_, swagger_html = openapi_handler.get_swagger_ui()
HTML(f'<iframe srcdoc="{html.escape(swagger_html, quote=True)}" width="100%" height="600" style="border:0"></iframe>')