2.1   Common syntactical constructs

# This is a comment
foaf:name: tmdm:topic-name # This is also a comment

<http://www.semagia.com/> # This is an IRI
<http://ws.mappify.org/rdf2tm/> # This, too ;)

foaf:name: tmdm:topic-name

# Equivalent statement:
<http://xmlns.com/foaf/0.1/name>: <http://psi.topicmaps.org/iso13250/model/topic-name>

# Maps the foaf:nick to the default name type and uses foaf:nick
# as scope
foaf:nick: tmdm:topic-name @foaf:nick

# Same as above, but assigns two themes
foaf:nick: tmdm:topic-name @foaf:nick, <http://psi.example.org/nickname>

2.2   Identities

While RDF knows just one identity type, Topic Maps provides two 'strong' identities (subject identifiers and subject locators) and one 'weak' identity type, the item identifiers.

CRTM provides support for all three identity types: the object may be mapped either to a subject identifier, a subject locator, or an item identifier.

A mapping to a subject identifier is either expresses through the keyword subject-identifier or sid:

foaf:mbox: subject-identifier

# Shotcut
foaf:mbox: sid

Subject locators can be established through the keyword subject-locator or slo:

foaf:img: subject-locator

# Shortcut
foaf:img: slo

Item identifiers are created through the keyword item-identifier or iid:

foaf:mbox: item-identifier

# Shotcut
foaf:mbox: iid

2.3   Occurrences

Occurrences are created with the keyword occurrence or the shortcut occ:

# Maps the foaf:homepage to an occurrence
foaf:homepage: occurrence

# Shortcut
foaf:homepage: occ

Optionally, a type and a scope may be specified:

# Overrides the foaf:homepage type with the specified type
foaf:homepage: occurrence <http://psi.example.org/homepage>

# Adding type and scope:
foaf:homepage: occurrence ex:homepage @lang:en

If a type and / or scope is specified, the keywords occurrence and occ are optional:

foaf:homepage: <http://psi.example.org/homepage>

foaf:homepage: ex:homepage @lang:en

foaf:homepage: @lang:en

2.4   Names

The notation for names is similar to the occurrence notation, except that the keyword is name. Alternatively, the hyphen - can be used to indicate that the RDF statement should be mapped to a topic name:

# Maps foaf:name to a topic name with the type foaf:name.
foaf:name: name

# Maps foaf:name to the default topic name type.
foaf:name: - tmdm:topic-name

# Maps foaf:nick to the default topic name type and adds foaf:nick to the scope
foaf:nick: - tmdm:topic-name @foaf:nick

# Equivalent statement; using the name keyword:
foaf:nick: name tmdm:topic-name @foaf:nick

2.5   Associations

Associations can be created with the (optional) keywords association or assoc followed by an optional type (if the RDF predicate should not be used as association type) followed by the role types and an optional scope:

# Creates an association where the subject and object play a role of type ``foaf:Person``
foaf:knows: association (foaf:Person, foaf:Person)

# Creates an association where the subject plays the ``ex:member`` role
# and the object the ``ex:group`` role.
ex:member-of: assoc(ex:member, ex:group)

The association keyword is optional:

# Same example as above
ex:member-of: (ex:member, ex:group)

Further, the association type can be overriden:

# The resulting association will have the type ex:parent-of rather than
# ex:child-of
ex:child-of: ex:parent-of(ex:child, ex:parent)

2.6   Type-Instance Relationship

While it is possible to model type-instance relationships with the notation for associations, CRTM provides a shortcut for it:

# Maps rdf:type to a type-instance association where the
# subject plays the tmdm:instance role and the object the tmdm:type role.
rdf:type: isa

Like associations, the type-instance shortcut accepts an optional scope.

2.7   Language Tags

Occurrences and names can utilize the optional RDF language tag which is translated into a topic which uses one of the OASIS ISO 639 PSIs [OASIS]. By default, the RDF language tags are ignored (for compatibility with [RTM]).

If the RDF source provides language tags they can be added to the scope of the occurrence:

foaf:homepage: occurrence; lang=true

The lang=true instruction advices the CRTM reader to convert the (optional) language tag into a topic which is added to the occurrence scope.

Given the following [Turtle] statements:

ex:tinyTiM dc:description "tinyTiM is a small Topic Maps engine"@en .
ex:tinyTiM dc:description "tinyTiM ist eine kleine Topic Maps Engine"@de .

the instruction:

dc:description: occurrence; lang=true

results into the following topic (using [CTM]):

%prefix lang <http://psi.oasis-open.org/iso/639/#>
# Other prefixes omitted

ex:tinytim
    dc:description: "tinyTiM is a small Topic Maps engine"@lang:eng;
    dc:description: "tinyTiM ist eine kleine Topic Maps Engine"@lang:deu.

CRTM offers also a global setting to translate the language tags and therefor it's also possible to disable the translation on a per statement basis:

dc:description: occurrence; lang=false

This would disable the translation of the language tag for the dc:description RDF predicate.

2.8   Prefix Directive

The prefix directive is used to associate an IRI with an identifier and to use QNames instead of more verbose IRIs.

Example:

%prefix ex <http://www.example.org/>

ex:foo: subject-identifier

In the example above the QName ex:foo is expanded to http://www.example.org/foo.

2.9   Language to Scope Directive

The language to scope directive enables / disables the translation of the optional RDF language tag for all occurrences and names.

Example:

%langtoscope true

dc:description: occurrence

Given the following [Turtle] statements:

ex:tinyTiM dc:description "tinyTiM is a small Topic Maps engine"@en .
ex:tinyTiM dc:description "tinyTiM ist eine kleine Topic Maps Engine"@de .

the resulting [CTM] topic would be:

%prefix lang <http://psi.oasis-open.org/iso/639/#>
# Other prefixes omitted

ex:tinytim
    dc:description: "tinyTiM is a small Topic Maps engine"@lang:eng;
    dc:description: "tinyTiM ist eine kleine Topic Maps Engine"@lang:deu.

Each mapping may override the global setting with setting lang to false:

%langtoscope true

dc:description: occurrence; lang=false

Results into:

ex:tinytim
    dc:description: "tinyTiM is a small Topic Maps engine";
    dc:description: "tinyTiM ist eine kleine Topic Maps Engine".

2.10   Include Directive

To create modular mappings or to reuse other mappings, CRTM offers the include directive:

%include <foaf.crtm>

The referenced mapping is added to the current CRTM instance. The IRI of the referenced mapping is resolved against the document locator of the current CRTM instance.

2.11   Predicate Lists

To shorten the code further, CRTM offers predicate lists which should be mapped to a Topic Maps construct.

The following statements:

foaf:familyName: name
foaf:firstName: name
foaf:givenName: name

can be folded into one statement:

foaf:familyName, foaf:firstName, foaf:givenName: name

That notation works for all CRTM instructions:

foaf:homepage, foaf:workInfoHomepage: subject-identifier

2.12   Grouped Statements

If a mapping is dedicated to a particular domain (i.e. the FOAF vocabulary), it could be cumbersome to type always QNames, therefor CRTM offers an alternative syntax:

%prefix foaf <http://xmlns.com/foaf/0.1/>

foaf {
  name: name
  nick: name
}

The identifiers within the curly braces are interpreted as local part of the a QName which the prefix "foaf". The grouped statements are not limited to one prefix, though:

%prefix doap <http://usefulinc.com/ns/doap#>
%prefix foaf <http://xmlns.com/foaf/0.1/>

doap {
  shortdesc, description: occurrence
}

foaf {
  name: name
  nick: name
}

As shown in the example above, it's also possible to use a list of identifers which should be mapped to a Topic Maps statement (doap:shortdesc and doap:description).