SKG-IF integration#
RAMOSE can expose any SPARQL triplestore as a SKG-IF compliant REST API.
Getting started#
1. Create the spec file#
RAMOSE specs are split into one API section and one operation section for each route. For an SKG-IF product API, define the API section first, then add one operation for the single-product route and one operation for the product search route.
In the API section, set #addon to ramose.skg_if. This loads the SKG-IF JSON-LD converter. Disable RAMOSE query parameters that are not part of the SKG-IF interface with #disable_params.
In each product operation, register the SKG-IF output with #format skg_if,to_skg_if,application/ld+json and make it the default with #default_format skg_if.
The search operation also defines the SKG-IF filter query parameter:
/products?filter=cf.search.title:OpenCitations,product_type:literature
In RAMOSE, this is a config-driven custom parameter. The #custom_params line points filter to a YAML file. The YAML file maps each accepted SKG-IF filter name to the SPARQL fragments injected into placeholders such as [[filter]].
The SPARQL queries must return the columns documented in Product CSV columns. Multiple rows per product are expected (one per combination of identifier, contributor, topic, etc.); the converter deduplicates and aggregates them.
#url /skg-if/v1
#type api
#base https://w3id.org/skg-if/sandbox/my-source
#title SKG-IF API for My Source
#description SKG-IF compliant API for My Source.
#version 1.0.0
#endpoint https://my-triplestore.example.org/sparql
#method get
#addon ramose.skg_if
#disable_params require,filter,sort,format,json
#url /products/{local_identifier}
#type operation
#method get
#description Returns a single research product.
#call /products/https://example.org/product/1
#format skg_if,to_skg_if,application/ld+json
#default_format skg_if
#sparql PREFIX dcterm: <http://purl.org/dc/terms/>
SELECT ?local_identifier ?product_type ?title ?title_lang
WHERE {
BIND(<[[local_identifier]]> AS ?local_identifier)
?local_identifier dcterm:title ?title .
# ... your triplestore-specific patterns here
}
#url /products
#type operation
#method get
#description Returns a list of research products matching the given filters.
#custom_params filter,skgif_filters.ocdm.yaml,Search filter.
#format skg_if,to_skg_if,application/ld+json
#default_format skg_if
#call /products?filter=cf.search.title:OpenCitations
#sparql [[filter_preamble]]
PREFIX dcterm: <http://purl.org/dc/terms/>
SELECT ?local_identifier ?product_type ?title ?title_lang
WHERE {
?local_identifier dcterm:title ?title .
[[filter]]
# ... your triplestore-specific patterns here
}
In this example, skgif_filters.ocdm.yaml decides what each search filter injects into the query. See config-driven parameters for the YAML syntax.
For a complete example, see the OpenCitations spec.
2. Run#
Start the built-in dev server:
ramose -s my_source.hf -w 127.0.0.1:8080
The API is served at http://127.0.0.1:8080/skg-if/v1.
For a runnable example querying ORKG and Wikidata, see the live demo notebook.
Product CSV columns#
Product operations use the columns listed below. Every SPARQL source must produce rows conforming to this schema. Multiple rows per product are expected (one per combination of identifier, contributor, citation, topic); the converter deduplicates and aggregates them.
Column names mirror JSON-LD output paths with dots replaced by underscores (SPARQL variable constraint). Columns prefixed with _ are internal to the converter and do not appear in the output.
Optional fields with no data are omitted from the output.
Only local_identifier and product_type are required at the product level.
Core metadata#
Official reference: Research product properties.
Column |
Description |
Example |
|---|---|---|
|
Primary key; groups all rows for one product |
|
|
SKG-IF product type: |
|
|
Product title |
|
|
ISO 639-1 language code for the title. Falls back to |
|
|
Product abstract |
|
|
ISO 639-1 language code for the abstract. Falls back to |
|
Product identifiers#
Official reference: identifiers.
Both identifier_scheme and identifier_value must be non-empty for an identifier to be included; rows where either is empty are skipped.
Column |
Description |
Example |
|---|---|---|
|
Identifier scheme for research products: |
|
|
The external identifier |
|
Contributions#
Official reference: contributions.
A contributor row is processed only when both contribution_role and _contribution_key are non-empty. The agent needs at least a family name, given name, or full name. Identifier scheme/value pairs and declared affiliation scheme/value pairs are co-dependent: both must be non-empty to be included.
Column |
Description |
Example |
|---|---|---|
|
The role of the contributing agent: |
|
|
CRediT contribution type: |
|
|
Family name. Its presence marks the contributor as a person |
|
|
Given name |
|
|
Full name (for organisations or agents without split names) |
|
|
Identifier scheme for the contributor: |
|
|
The external identifier of the contributor |
|
|
Contributor local identifier |
|
|
Name of the declared affiliation organisation |
|
|
Short name or acronym of the affiliation |
|
|
ISO 3166-1 alpha-2 country code of the affiliation (e.g., IT) |
|
|
Affiliation local identifier |
|
|
Identifier scheme for the affiliation: |
|
|
The external identifier of the affiliation |
|
|
Organisation type: |
|
|
Website URL of the affiliation |
|
|
Alternative name of the affiliation |
|
See also Internal columns for contributor deduplication and ordering.
Internal#
These columns are consumed by the converter for deduplication and ordering. They do not appear in the JSON-LD output.
Column |
Description |
Example |
|---|---|---|
|
Deduplication key for contributors; also serves as the node identifier in the linked list that determines ordering within each role |
|
|
Points to the |
|
Contributors are ordered by role (author, then editor, then publisher) and within each role by the linked list formed by _contribution_key / _contribution_next_key.
Topics#
Official reference: topics.
topic_term anchors each topic entry; rows without it are skipped. Identifier and provenance fields are pairwise co-dependent: topic_identifier_scheme/topic_identifier_value and topic_provenance_associated_with/topic_provenance_trust must both be non-empty.
Column |
Description |
Example |
|---|---|---|
|
|
|
|
Identifier scheme for the topic: |
|
|
The external identifier of the topic |
|
|
Label describing the topic |
|
|
ISO 639-1 language code for the topic label. Falls back to |
|
|
|
|
|
Trust value for the relation, normalized to [0,1]. Provenance entries without trust are skipped |
|
Manifestations#
Official reference: manifestations.
All fields are individually optional. Co-dependent pairs: manifestation_identifier_scheme/manifestation_identifier_value, manifestation_dates_type/manifestation_dates_value, manifestation_biblio_pages_first/manifestation_biblio_pages_last. Venue and hosting data source identifier pairs follow the same pattern.
Column |
Description |
Example |
|---|---|---|
|
The URL of the class identifying the manifestation type (e.g. |
|
|
Label describing the manifestation type (e.g. |
|
|
ISO 639-1 language code for the type label. Falls back to |
|
|
Identifier scheme for the manifestation (distinct from product-level identifiers): |
|
|
The external identifier of the manifestation |
|
|
The type of date: |
|
|
ISO 8601 date string; partial values like |
|
|
Peer review status: |
|
|
Peer review type: |
|
|
Access status: |
|
|
Qualification of the access status |
|
|
The URL of the licence for the manifestation |
|
|
Version identifier (for software or research data manifestations) |
|
|
Volume number |
|
|
Issue number |
|
|
The edition (for journals and books) |
|
|
Manifestation number within the venue (e.g., chapter number) |
|
|
The starting page. Both |
|
|
The ending page |
|
|
Venue name. Its presence triggers the venue sub-object |
|
|
Venue local identifier |
|
|
Identifier scheme for the venue: |
|
|
Venue identifier value |
|
|
Venue acronym or short name |
|
|
Local identifier of the data source hosting the manifestation. Its presence triggers the hosting data source sub-object |
|
|
Name of the hosting data source |
|
|
Identifier scheme for the hosting data source |
|
|
Identifier value for the hosting data source |
|
Funding#
Official reference: funding.
funding_local_identifier anchors each grant entry; rows without it are skipped. funding_agency_name must be non-empty for the agency sub-object to be built. Identifier pairs (funding_identifier_scheme/funding_identifier_value and funding_agency_identifier_scheme/funding_agency_identifier_value) are co-dependent.
Column |
Description |
Example |
|---|---|---|
|
Grant local identifier |
|
|
Grant number |
|
|
Grant title |
|
|
ISO 639-1 language code for the grant title. Falls back to |
|
|
Grant abstract |
|
|
ISO 639-1 language code for the grant abstract. Falls back to |
|
|
Grant acronym |
|
|
Identifier scheme for the grant |
|
|
The external identifier of the grant |
|
|
Funding stream (e.g. “Horizon Europe”) |
|
|
Name of the funding agency |
|
|
Short name of the funding agency |
|
|
ISO 3166-1 alpha-2 country code of the funding agency |
|
|
Funding agency local identifier |
|
|
Identifier scheme for the funding agency |
|
|
The external identifier of the funding agency |
|
|
Organisation type of the funding agency: |
|
|
Website URL of the funding agency |
|
Relevant organisations#
Official reference: relevant_organisations.
A row is included when it has at least a relevant_organisation_name or relevant_organisation_local_identifier. Identifier scheme/value pairs are co-dependent.
Column |
Description |
Example |
|---|---|---|
|
Organisation name |
|
|
Short name or acronym |
|
|
ISO 3166-1 alpha-2 country code |
|
|
Organisation local identifier |
|
|
Identifier scheme for the organisation |
|
|
The external identifier of the organisation |
|
|
Organisation type: |
|
|
Website URL of the organisation |
|
|
Alternative name of the organisation |
|