Knowledge Graph - Mapping Dsl Builder

Dev Tools

Generate declarative mapping rules that transform structured data sources into graph triples or nodes using a domain-specific mapping language similar to R2RML.

Install

openclaw skills install mapping-dsl-builder

Mapping DSL Builder

Generate declarative mapping rules for transforming data into graph structures.

This skill creates domain-specific language (DSL) mappings that define how data fields from structured sources such as databases, CSV files, JSON, or APIs should be transformed into nodes, relationships, and triples for graph databases or knowledge graphs. The mapping language functions similarly to R2RML, the standard for relational-to-RDF mappings.

Quick Start

Use When

Defining mappings between structured datasets and graph models
Creating declarative transformation rules
Converting relational schemas into RDF triples
Building graph ingestion mapping specifications
Generating reusable data-to-graph mapping configurations
Standardizing ETL transformation definitions

Inputs

Source schema definitions (database, CSV, JSON, API)
Entity type specifications
Column/property definitions
Foreign key relationships
Identifier specifications
Mapping rules and transformations
Target graph schema

Outputs

Custom Mapping DSL specifications
R2RML (RDF Mapping Language) definitions
YAML mapping configurations
JSON mapping specifications
Property graph mappings
Executable mapping configurations
Data transformation documentation

Example

Input Database Schema:

CREATE TABLE employee (
  id INT,
  name VARCHAR(255),
  email VARCHAR(255),
  company_id INT
);

CREATE TABLE company (
  id INT,
  name VARCHAR(255),
  industry VARCHAR(100)
);

Generated Mapping DSL:

mapping: EmployeeMapping
version: 1.0

source:
  type: database
  table: employee
  connection: postgresql://localhost/company_db

entity:
  type: Person
  identifier: id
  uri_template: "http://example.org/person/{id}"

properties:
  - source: name
    target: http://xmlns.com/foaf/0.1/name
    type: string
  - source: email
    target: http://xmlns.com/foaf/0.1/mbox
    type: string

relationships:
  - name: WORKS_AT
    source: company_id
    target: Company
    target_identifier: id

Mapping DSL Architecture

1. Source Definition

Purpose: Specify where data comes from

Types Supported:

Database - SQL databases (PostgreSQL, MySQL, Oracle)
CSV - Comma/delimiter-separated files
JSON - JSON files or documents
API - REST API endpoints
Streaming - Real-time data streams

Configuration:

source:
  type: database|csv|json|api|stream
  connection_string: connection_details
  table_or_location: specification
  format: format_options

2. Entity Mapping

Purpose: Define how records map to graph entities

Components:

Type - Entity type/label (Person, Organization, etc.)
Identifier - Column(s) that uniquely identify records
URI Template - Pattern for generating entity URIs
Properties - Attributes to include

Configuration:

entity:
  type: EntityType
  identifier: id_column
  uri_template: "http://example.org/type/{id}"
  namespace: http://example.org/

3. Property Mapping

Purpose: Map source attributes to graph properties

Details:

Source column name
Target property URI
Data type
Transformations (optional)
Default values (optional)

Configuration:

properties:
  - source: database_column
    target: http://schema.org/propertyName
    type: string|integer|date
    transformation: function_name
    required: true|false

4. Relationship Mapping

Purpose: Define relationships between entities

Details:

Relationship name/type
Source column (foreign key)
Target entity
Cardinality
Direction

Configuration:

relationships:
  - name: RELATIONSHIP_TYPE
    source: foreign_key_column
    target: TargetEntity
    target_identifier: target_id
    cardinality: "1..1"|"1..*"|"*..1"|"*..*"
    direction: forward|backward|bidirectional

Mapping Patterns

Database Mapping Pattern

Pattern: Map relational table to graph entity

source:
  type: database
  table: employee
relationships:
  - name: WORKS_AT
    source: company_id (foreign key)
    target: Company entity

CSV Mapping Pattern

Pattern: Map CSV columns to graph properties

source:
  type: csv
  file: data/employees.csv
  delimiter: ","
entity:
  identifier: person_id (unique column)
properties:
  - source: name
    target: foaf:name

JSON Mapping Pattern

Pattern: Map JSON properties to graph structure

source:
  type: json
  path: $.employees[*]
entity:
  identifier: $.id
properties:
  - source: $.name
    target: http://example.org/name

Nested Object Mapping Pattern

Pattern: Handle nested structures

source:
  type: json
  path: $.employees[*]
relationships:
  - name: HAS_ADDRESS
    source: $.address (nested object)
    target: Address
    inline: true

Output Formats

Custom Mapping DSL

mapping: PersonMapping
version: 1.0

source:
  type: csv
  file: people.csv

entity:
  type: Person
  identifier: person_id

properties:
  - source: name
    target: foaf:name
  - source: email
    target: foaf:mbox

relationships:
  - name: WORKS_AT
    source: company_id
    target: Company

R2RML Format

@prefix rr: <http://www.w3.org/ns/r2rml#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix ex: <http://example.org/> .

ex:EmployeeMapping a rr:TriplesMap ;
  rr:logicalTable [ rr:tableName "employee" ] ;
  rr:subjectMap [
    rr:template "http://example.org/person/{id}" ;
    rr:class foaf:Person
  ] ;
  rr:predicateObjectMap [
    rr:predicate foaf:name ;
    rr:objectMap [ rr:column "name" ]
  ] ;
  rr:predicateObjectMap [
    rr:predicate foaf:workplaceHomepage ;
    rr:objectMap [
      rr:parentTriplesMap ex:CompanyMapping ;
      rr:joinCondition [ rr:child "company_id" ; rr:parent "id" ]
    ]
  ] .

YAML Format

version: 1.0
mappings:
  - name: PersonMapping
    source:
      type: database
      table: person
    entity:
      type: Person
      id: person_id
    properties:
      name: name
      email: email_address
    relationships:
      works_at:
        target: Company
        foreign_key: company_id

Data Type Support

Supported Types

string - Text data
integer - Whole numbers
decimal - Floating point numbers
boolean - True/false values
date - Date values (YYYY-MM-DD)
datetime - Date and time
uri - Uniform resource identifiers
custom - User-defined types

Type Mapping

Relational → RDF Type Mapping
INTEGER → xsd:integer
VARCHAR → xsd:string
DATE → xsd:date
DECIMAL → xsd:decimal
BOOLEAN → xsd:boolean

Transformation Functions

Built-in Transformations

concat(field1, field2)    - Concatenate fields
uppercase(field)          - Convert to uppercase
lowercase(field)          - Convert to lowercase
substring(field, 0, 5)    - Extract substring
replace(field, old, new)  - Replace values
regex(field, pattern)     - Regex matching
split(field, delimiter)   - Split string
trim(field)               - Remove whitespace

Execution Steps

Analyze Source Schema – Detect structure and data types
Identify Entities – Find key identifiers
Detect Relationships – Recognize foreign keys
Map Properties – Associate columns to properties
Generate URIs – Create entity identifiers
Define Transformations – Apply any conversions
Validate Mapping – Check for consistency
Generate Output – Produce mapping specifications

Recommended Libraries

Mapping Processing: rdflib, r2rml-processor, morph-kgc
DSL Generation: pyparsing, lark, textx
Schema Analysis: sqlalchemy, pandas, jsonschema
RDF Generation: rdflib, sparql-client
YAML/Config: pyyaml, toml, configparser
Database: sqlalchemy, psycopg2, pymongo

Best Practices

✓ Use consistent URI templates
✓ Choose meaningful identifiers
✓ Document mapping rationale
✓ Normalize property names
✓ Handle missing values explicitly
✓ Test mappings with sample data
✓ Version mapping configurations
✓ Document transformations
✓ Validate schemas before mapping
✓ Keep mappings reusable

Integration with Downstream Skills

Generated mappings are used by:

ETL Pipeline Generator – Execute mappings in pipelines
JSON to Triples Converter – Transform JSON using mappings
CSV Graph Loader Generator – Load CSV with defined mappings
Graph Schema Validation – Validate mapped data
Graph Constraint Generator – Apply constraints to mapped data

References

See mapping-patterns.md for detailed mapping design patterns and example-mappings.md for complete real-world examples.

Version: 1.0.0

Knowledge Graph - Mapping Dsl Builder

Install

Mapping DSL Builder

Quick Start

Use When

Inputs

Outputs

Example

Mapping DSL Architecture

1. Source Definition

2. Entity Mapping

3. Property Mapping

4. Relationship Mapping

Mapping Patterns

Database Mapping Pattern

CSV Mapping Pattern

JSON Mapping Pattern

Nested Object Mapping Pattern

Output Formats

Custom Mapping DSL

R2RML Format

YAML Format

Data Type Support

Supported Types

Type Mapping

Transformation Functions

Built-in Transformations

Execution Steps

Recommended Libraries

Best Practices

Integration with Downstream Skills

References

Related skills