RML Mapping API

This page documents the public, user-facing classes for generating and executing RML mappings. These classes are useful when you want a reusable mapping file instead of directly converting input data to triples.

The most convenient entry point is DefaultMappingGenerator:

generator = DefaultMappingGenerator()
generator.generate_mappings("geojson", "data/pois.geojson", "mappings/pois.ttl")
generator.generate_triples("mappings/pois.ttl", "out/pois.nt")

`DefaultMappingGenerator` source 

class DefaultMappingGenerator(
    ontology_uri="https://example.org/ontology/",
    resource_uri="https://example.org/resource/",
)

High-level utility for generating default RML mappings and materializing triples from those mappings. This is the class most users should start with.

Parameters

Parameter	Type	Default	Description
`ontology_uri`	`str`	`"https://example.org/ontology/"`	URI prefix used for generated predicates/classes in the mapping.
`resource_uri`	`str`	`"https://example.org/resource/"`	URI prefix used for generated subject/object resources.

Methods

`DefaultMappingGenerator.generate_mappings(type, input_file, mapping_file)` source 

generate_mappings(type, input_file, mapping_file)

Generate a default RML mapping file for the selected input type.

Parameter	Type	Default	Description
`type`	`str`	required	Input format. Supported values are `"json"`, `"csv"`, `"xml"`, and `"geojson"`.
`input_file`	`str`	required	Path to the input data source.
`mapping_file`	`str`	required	Path where the generated RML mapping file will be written.

Raises: Exception if type is not supported.

`DefaultMappingGenerator.generate_triples(mapping_file, output_file)` source 

generate_triples(mapping_file, output_file)

Materialize triples from an RML mapping and serialize the result as N-Triples.

Parameter	Type	Default	Description
`mapping_file`	`str`	required	Path to an RML mapping file.
`output_file`	`str`	required	Path where the generated N-Triples file will be written.

Raises: RuntimeError if graph serialization fails.

Example

from toposkg.converter.rml.toposkg_lib_default_mapping_generator import DefaultMappingGenerator

generator = DefaultMappingGenerator(
    ontology_uri="https://example.org/ontology/",
    resource_uri="https://example.org/resource/",
)
generator.generate_mappings("csv", "data/places.csv", "mappings/places.ttl")
generator.generate_triples("mappings/places.ttl", "out/places.nt")

`CSVMappingGenerator` source 

class CSVMappingGenerator(ontology_uri, resource_uri)

Format-specific default RML mapping generator for CSV files. It creates an intermediate CSV file with a generated ID column and builds a single TriplesMap over the CSV columns.

Parameters

Parameter	Type	Default	Description
`ontology_uri`	`str`	required	URI prefix used for generated predicates/classes.
`resource_uri`	`str`	required	URI prefix used for generated resources.

Methods

`CSVMappingGenerator.generate_default_mapping(input_data_source)` source 

generate_default_mapping(input_data_source)

Generate default CSV mapping objects and store them in self.maps.

Parameter	Type	Default	Description
`input_data_source`	`str`	required	Path to the input CSV file.

Note: Unlike the JSON/XML/GeoJSON mapping generators, this implementation populates self.maps but does not return the mapping string directly. Use RMLBuilder to export self.maps.

`JSONMappingGenerator` source 

class JSONMappingGenerator(ontology_uri, resource_uri)

Format-specific default RML mapping generator for JSON files. It creates an intermediate JSON file with generated IDs and parent IDs, recursively builds TriplesMap objects, and exports them as an RML mapping string.

Parameters

Parameter	Type	Default	Description
`ontology_uri`	`str`	required	URI prefix used for generated predicates/classes.
`resource_uri`	`str`	required	URI prefix used for generated resources.

Methods

`JSONMappingGenerator.generate_default_mapping(input_data_source)` source 

generate_default_mapping(input_data_source)

Generate and return a default RML mapping string for a JSON file.

Parameter	Type	Default	Description
`input_data_source`	`str`	required	Path to the input JSON file.

Returns: str containing the generated RML mapping.

`GeoJSONMappingGenerator` source 

class GeoJSONMappingGenerator(ontology_uri, resource_uri)

Format-specific default RML mapping generator for GeoJSON files. It augments the input with generated IDs, transforms geometry dictionaries to WKT where possible, and creates RML mappings over the resulting JSON structure.

Parameters

Parameter	Type	Default	Description
`ontology_uri`	`str`	required	URI prefix used for generated predicates/classes.
`resource_uri`	`str`	required	URI prefix used for generated resources.

Methods

`GeoJSONMappingGenerator.generate_default_mapping(input_data_source)` source 

generate_default_mapping(input_data_source)

Generate and return a default RML mapping string for a GeoJSON file.

Parameter	Type	Default	Description
`input_data_source`	`str`	required	Path to the input GeoJSON file.

Returns: str containing the generated RML mapping.

`XMLMappingGenerator` source 

class XMLMappingGenerator(ontology_uri, resource_uri)

Format-specific default RML mapping generator for XML files. It creates an intermediate XML file with generated ID and parent ID attributes, then builds XPath-based RML TriplesMap objects.

Parameters

Parameter	Type	Default	Description
`ontology_uri`	`str`	required	URI prefix used for generated predicates/classes.
`resource_uri`	`str`	required	URI prefix used for generated resources.

Methods

`XMLMappingGenerator.generate_default_mapping(input_data_source)` source 

generate_default_mapping(input_data_source)

Generate and return a default RML mapping string for an XML file.

Parameter	Type	Default	Description
`input_data_source`	`str`	required	Path to the input XML file.

Returns: str containing the generated RML mapping.

`RMLBuilder` source 

class RMLBuilder(ontology_uri, resource_uri, maps=[])

Utility class for combining one or more TriplesMap objects into a complete RML mapping document with the standard prefixes used by the library.

Parameters

Parameter	Type	Default	Description
`ontology_uri`	`str`	required	URI used to define the `onto:` prefix in the generated mapping.
`resource_uri`	`str`	required	URI used to define the `resource:` prefix in the generated mapping.
`maps`	`list[TriplesMap]`	`[]`	Triples maps to include in the exported mapping document.

Methods

`RMLBuilder.load_prefixes()` source 

load_prefixes()

Return the default RML/R2RML, XSD, GeoSPARQL, ontology, and resource prefixes used by the generated mapping.

Returns: list[str] containing prefix declarations.

`RMLBuilder.export_as_string()` source 

export_as_string()

Export all configured TriplesMap objects as a single RML mapping string.

Returns: str containing the complete mapping document.

`TriplesMap` source 

class TriplesMap(ontology_uri, resource_uri, name=None)

Programmatic builder for a single RML/R2RML rr:TriplesMap. Use this class when you want to manually define the logical source, subject map, predicate-object maps, joins, or template object maps.

Parameters

Parameter	Type	Default	Description
`ontology_uri`	`str`	required	URI prefix used for generated ontology terms.
`resource_uri`	`str`	required	URI prefix used in generated subject templates.
`name`	`str \| None`	`None`	Optional triples map name. If omitted, it is derived from the input source in `add_logical_source()`.

Methods

`TriplesMap.add_logical_source(input_data_source, reference_formulation, iterator=None)` source 

add_logical_source(input_data_source, reference_formulation, iterator=None)

Define the RML logical source for this triples map.

Parameter	Type	Default	Description
`input_data_source`	`str`	required	Path to the input data source referenced by the mapping.
`reference_formulation`	`str`	required	RML reference formulation, for example `"ql:CSV"`, `"ql:JSONPath"`, or `"ql:XPath"`.
`iterator`	`str \| None`	`None`	Optional iterator, such as a JSONPath or XPath expression.

`TriplesMap.add_subject_map(id_field, subject_class=None, graph=None)` source 

add_subject_map(id_field, subject_class=None, graph=None)

Define the subject map template for generated subjects.

Parameter	Type	Default	Description
`id_field`	`str`	required	Field/reference used inside the generated subject URI template.
`subject_class`	`str \| None`	`None`	Optional class name emitted as `rr:class onto:<subject_class>`.
`graph`	`str \| None`	`None`	Optional graph URI used to create an `rr:graphMap`.

`TriplesMap.add_predicate_object_map(predicate_name, reference, datatype=None, prefix=None)` source 

add_predicate_object_map(predicate_name, reference, datatype=None, prefix=None)

Add a predicate-object map that reads literal values from a source reference.

Parameter	Type	Default	Description
`predicate_name`	`str`	required	Predicate local name. By default it is emitted under the `onto:` prefix.
`reference`	`str`	required	Source field/reference used as the object value.
`datatype`	`str \| None`	`None`	Optional datatype hint. Recognized values include `"bool"`, `"int"`, `"float"`, `"wkt"`; other values default to string.
`prefix`	`str \| None`	`None`	Optional prefix override for the predicate.

`TriplesMap.add_predicate_object_map_on_join(predicate_name, foreign_map, child, parent)` source 

add_predicate_object_map_on_join(predicate_name, foreign_map, child, parent)

Add a predicate-object map that joins this map with another triples map.

Parameter	Type	Default	Description
`predicate_name`	`str`	required	Predicate local name for the relationship.
`foreign_map`	`TriplesMap`	required	Parent/target triples map.
`child`	`str`	required	Child join field.
`parent`	`str`	required	Parent join field.

`TriplesMap.add_predicate_object_map_on_reference(predicate_name, refObjectMap)` source 

add_predicate_object_map_on_reference(predicate_name, refObjectMap)

Add a predicate-object map that points to a separately declared rr:RefObjectMap.

Parameter	Type	Default	Description
`predicate_name`	`str`	required	Predicate local name for the relationship.
`refObjectMap`	`str`	required	Reference object map identifier.

`TriplesMap.add_predicate_object_map_with_template(predicate_name, template, prefix=None)` source 

add_predicate_object_map_with_template(predicate_name, template, prefix=None)

Add a predicate-object map whose object is generated from an RML/R2RML template.

Parameter	Type	Default	Description
`predicate_name`	`str`	required	Predicate local name.
`template`	`str`	required	Object URI template.
`prefix`	`str \| None`	`None`	Optional predicate prefix override.

`TriplesMap.add_ref_object_map(name, parentMap, child, parent)` source 

add_ref_object_map(name, parentMap, child, parent)

Register a reusable reference object map.

Parameter	Type	Default	Description
`name`	`str`	required	RefObjectMap identifier.
`parentMap`	`TriplesMap`	required	Parent triples map.
`child`	`str`	required	Child join field.
`parent`	`str`	required	Parent join field.

`TriplesMap.export_as_string()` source 

export_as_string()

Serialize this triples map as an RML mapping fragment.

Returns: str containing the mapping fragment.

Raises: Exception if the logical source or subject map has not been initialized.

Example

from toposkg.converter.rml.toposkg_lib_triples_map import TriplesMap
from toposkg.converter.rml.toposkg_lib_mapping_builder import RMLBuilder

places = TriplesMap(
    ontology_uri="https://example.org/ontology/",
    resource_uri="https://example.org/resource/",
    name="PlacesMap",
)
places.add_logical_source("data/places.csv", "ql:CSV")
places.add_subject_map("id", subject_class="Place")
places.add_predicate_object_map("name", "name", datatype="string")
places.add_predicate_object_map("population", "population", datatype="int")

builder = RMLBuilder(
    ontology_uri="https://example.org/ontology/",
    resource_uri="https://example.org/resource/",
    maps=[places],
)
mapping = builder.export_as_string()

`RMLModule` source 

class RMLModule()

Small wrapper around morph_kgc for materializing RDF triples from an RML mapping file.

Methods

`RMLModule.generate_triples(mapping_file)` source 

generate_triples(mapping_file)

Materialize RDF triples from a mapping file.

Parameter	Type	Default	Description
`mapping_file`	`str`	required	Path to the RML mapping file.

Returns: rdflib.Graph containing the materialized triples.

Example

from toposkg.converter.rml.toposkg_lib_rml_module import RMLModule

module = RMLModule()
graph = module.generate_triples("mappings/places.ttl")
graph.serialize(destination="out/places.nt", format="nt")

RML Mapping API

DefaultMappingGenerator source

Parameters

Methods

DefaultMappingGenerator.generate_mappings(type, input_file, mapping_file) source

DefaultMappingGenerator.generate_triples(mapping_file, output_file) source

Example

CSVMappingGenerator source

Parameters

Methods

CSVMappingGenerator.generate_default_mapping(input_data_source) source

JSONMappingGenerator source

Parameters

Methods

JSONMappingGenerator.generate_default_mapping(input_data_source) source

GeoJSONMappingGenerator source

Parameters

Methods

GeoJSONMappingGenerator.generate_default_mapping(input_data_source) source

XMLMappingGenerator source

Parameters

Methods

XMLMappingGenerator.generate_default_mapping(input_data_source) source

RMLBuilder source

Parameters

Methods

RMLBuilder.load_prefixes() source

RMLBuilder.export_as_string() source

TriplesMap source

Parameters

Methods

TriplesMap.add_logical_source(input_data_source, reference_formulation, iterator=None) source

TriplesMap.add_subject_map(id_field, subject_class=None, graph=None) source

TriplesMap.add_predicate_object_map(predicate_name, reference, datatype=None, prefix=None) source

TriplesMap.add_predicate_object_map_on_join(predicate_name, foreign_map, child, parent) source

TriplesMap.add_predicate_object_map_on_reference(predicate_name, refObjectMap) source

TriplesMap.add_predicate_object_map_with_template(predicate_name, template, prefix=None) source

TriplesMap.add_ref_object_map(name, parentMap, child, parent) source

TriplesMap.export_as_string() source

Example

RMLModule source

Methods

RMLModule.generate_triples(mapping_file) source

Example

`DefaultMappingGenerator` source 

`DefaultMappingGenerator.generate_mappings(type, input_file, mapping_file)` source 

`DefaultMappingGenerator.generate_triples(mapping_file, output_file)` source 

`CSVMappingGenerator` source 

`CSVMappingGenerator.generate_default_mapping(input_data_source)` source 

`JSONMappingGenerator` source 

`JSONMappingGenerator.generate_default_mapping(input_data_source)` source 

`GeoJSONMappingGenerator` source 

`GeoJSONMappingGenerator.generate_default_mapping(input_data_source)` source 

`XMLMappingGenerator` source 

`XMLMappingGenerator.generate_default_mapping(input_data_source)` source 

`RMLBuilder` source 

`RMLBuilder.load_prefixes()` source 

`RMLBuilder.export_as_string()` source 

`TriplesMap` source 

`TriplesMap.add_logical_source(input_data_source, reference_formulation, iterator=None)` source 

`TriplesMap.add_subject_map(id_field, subject_class=None, graph=None)` source 

`TriplesMap.add_predicate_object_map(predicate_name, reference, datatype=None, prefix=None)` source 

`TriplesMap.add_predicate_object_map_on_join(predicate_name, foreign_map, child, parent)` source 

`TriplesMap.add_predicate_object_map_on_reference(predicate_name, refObjectMap)` source 

`TriplesMap.add_predicate_object_map_with_template(predicate_name, template, prefix=None)` source 

`TriplesMap.add_ref_object_map(name, parentMap, child, parent)` source 

`TriplesMap.export_as_string()` source 

`RMLModule` source 

`RMLModule.generate_triples(mapping_file)` source 