YARRRML

YARRRML is a YAML-friendly syntax for RML mappings.

Note

Minimal generator. JSON-first. Good starting point for hand-tuning.

Example Output

Given a simple schema:

classes:
  Person:
    attributes:
      id: {identifier: true}
      name: {}

The generator produces YARRRML like:

mappings:
  Person:
    sources:
      - - data.json~jsonpath
        - $.items[*]
    s: ex:$(id)
    po:
      - p: rdf:type
        o: ex:Person
      - p: ex:name
        o: $(name)

CSV / TSV sources

Besides JSON, CSV/TSV is supported. The key differences:

  • No iterator is required for CSV/TSV (each row is a candidate).

  • sources must be expressed as a list of lists for compatibility with common engines (e.g. Morph-KGC):

    mappings:
  Person:
    sources:
      - ['people.csv~csv']   # note the inner list
    s: ex:$(id)
    po:
      - p: rdf:type
        o: ex:Person
      - p: ex:name
        o: $(name)

  • Values come directly from columns via $(column_name).

  • For object slots (non-inlined references), IRIs are emitted:

    - p: ex:employer
  o:
    value: $(employer)
    type: iri

  • TSV works via the same formulation (~csv). Most engines auto-detect the tab separator for .tsv files. If an engine requires explicit delimiter/CSVW options, that is currently out of scope and can be handled manually in post-editing.

Source inference

If a file path is passed without a formulation suffix, the generator infers it automatically:

  • *.json → ~jsonpath

  • *.csv / *.tsv → ~csv

Examples:

# JSON (iterator required)
linkml generate yarrrml schema.yaml > mappings.yml
linkml generate yarrrml schema.yaml --source data.json~jsonpath
linkml generate yarrrml schema.yaml --source data.json~jsonpath --iterator-template "$.{Class}[*]"

# CSV / TSV (no iterator)
linkml generate yarrrml schema.yaml --source people.csv
linkml generate yarrrml schema.yaml --source people.tsv~csv

# CLI alias (short form)
gen-yarrrml schema.yaml --source data.csv~csv > mappings.yml

Overview

  • one mapping per LinkML class

  • prefixes come from the schema

  • subject from identifier slot (else key; else safe fallback)

  • po for all class attributes (slot aliases respected)

  • emits rdf:type as CURIEs (e.g., ex:Person)

  • JSON by default: sources: [[data.json~jsonpath, $.items[*]]]

  • CSV/TSV: sources: [[path~csv]] (no iterator), values via $(column)

Command Line

linkml generate yarrrml path/to/schema.yaml > mappings.yml
# CSV instead of JSON:
linkml generate yarrrml path/to/schema.yaml --source data.csv~csv
# class-based JSON arrays:
linkml generate yarrrml path/to/schema.yaml --iterator-template "$.{Class}[*]"
# or short alias:
gen-yarrrml path/to/schema.yaml --source data.csv~csv > mappings.yml

Docs

CLI

gen-yarrrml

Generate YARRRML mappings from a LinkML schema.

gen-yarrrml [OPTIONS] YAMLFILE

Options

--source <source>

YARRRML source shorthand, e.g., data.json~jsonpath or data.csv~csv (TSV works too)

--iterator-template <iterator_template>

JSONPath iterator template; supports {Class}, default: “$.items[*]”

-V, --version

Show the version and exit.

-f, --format <format>

Output format

Default:

'yml'

Options:

yml | yaml

--metadata, --no-metadata

Include metadata in output

Default:

True

--useuris, --metauris

Use class and slot URIs over model uris

Default:

True

-im, --importmap <importmap>

Import mapping file

--log_level <log_level>

Logging level

Default:

'WARNING'

Options:

CRITICAL | ERROR | WARNING | INFO | DEBUG

-v, --verbose

Verbosity. Takes precedence over –log_level.

--mergeimports, --no-mergeimports

Merge imports into source file (default=mergeimports)

--stacktrace, --no-stacktrace

Print a stack trace when an error occurs

Default:

False

Arguments

YAMLFILE

Required argument

Code

class linkml.generators.yarrrmlgen.YarrrmlGenerator(schema: str | TextIO | SchemaDefinition, format: str = 'yml', **kwargs)[source]
serialize(**args) → str[source]

Generate output in the required format

Parameters:

kwargs – Generator specific parameters

Returns:

Generated output

Limitations

  • JSON-first by default

  • One source per mapping

  • Classes without an identifier are assigned a fallback subject: ex:<Class>/$(subject_id)

  • Object slots: inlined: false → IRI; inlined: true → included as separate mapping

  • Iterators not derived from JSON Schema

  • No per-slot JSONPath/CSV expressions or functions

  • CSV/TSV supported via --source; delimiter/custom CSVW options are not yet exposed