CTM - Use Case Solutions

This section contains use cases to create topics. Additionally this section defines use cases for creating type-instance relationships between topics. While the type-instance relationship is created with an association, the authors of this document assume that each syntax has a short hand notation for this common use case.

3.1.1. Topic with an Item Identifier

AsTMa=
```
john
```
LTM

3.1.2. Typed Topic - Using Item Identifiers

AsTMa=

john (person)

# Alternative: Using the built-in association template "is-a" that creates
# an type-instance association where the far left topic becomes the instance
# and the right topic becomes the type:

john is-a person

3.1.3. Typed Topic - Using Subject Identifiers

AsTMa=

# AsTMa= uses the "i'" prefix to indicate that a URI is a subject identifier

john (i'http://psi.example.org/person)

# or:

john is-a i'http://psi.example.org/person


# Also possible (using the prefix directive)
# The i' in front indicates that the URI can only be used as subject identifier!

%prefix ex i'http://psi.example.org/

john is-a ex:person
john (ex:person)

3.1.4. Multi Typed Topic - Using Item Identifiers

AsTMa=

john (person musician)

# or

john is-a person is-a musician

3.1.5. Multi Typed Topic - Using Subject Identifiers

AsTMa=

john (i'http://psi.example.org/person i'http://psi.example.org/musician)

# Solutions for "is-a" and the prefix directive omitted, see 3.1.3 and 3.1.4

3.2. Assigning Topic Names to a Topic

This section contains use cases to create topic names and their variant names.

3.2.1. Topic with an Item Identifier and a Topic Name

AsTMa=

john
tn: John Lennon

# It's also possible to use quotes (either " or ') to 
# mark the begin and end of values

john
tn: "John Lennon"

john
tn: 'John Lennon'

3.2.2. Topic with a Subject Identifier and a Topic Name

AsTMa=
```
i'http://beatles.com/
tn: The Beatles
```
LTM

3.2.3. Topic with a Subject Locator and a Topic Name

AsTMa=

# An URI with no prefix is used to indicate subject locators

http://beatles.com/
tn: Official website of The Beatles

3.2.4. Typed Topic Name - Using Item Identifiers

AsTMa=
```
john
tn (fullname): John Ono Lennon
```
LTM

3.2.5. Typed Topic Name - Using Subject Identifiers

AsTMa=

john
tn (i'http://psi.example.org/fullname ): John Ono Lennon

# Again, prefixes may be used:

%prefix ex i'http://psi.example.org/
john
tn (ex:fullname): John Ono Lennon

# Or, with an 'unqualified' prefix defintion:

%prefix ex http://psi.example.org/

tn (i'ex:fullname): John Ono Lennon

3.2.6. Scoped Topic Name - Using Item Identifiers

AsTMa=
```
john
tn @fullname: John Winston Lennon
```
LTM

3.2.7. Scoped Topic Name - Using Subject Identifiers

AsTMa=

john
tn @i'http://example.org/fullname: John Winston Lennon

# Using prefixes is also allowed here, see 3.2.5 for an example

3.2.8. Multi Scoped Topic Name

AsTMa=

beatles
tn: The Beatles
tn @nickname short: Fab Four

3.2.9. Typed and Scoped Topic Name

AsTMa=

john
tn @yoko (fullname): John Ono Lennon

3.2.10. Topic Name with a Variant of datatype String

AsTMa=

john
tn: John Lennon
var @sortname: lennon, john

# AsTMa= v2.0 assumes automatically that the datatype of the variant is
# http://www.w3.org/2001/XMLSchema#string if the value does not
# begin with a known URI protocol. It is also possible to make 
# this explicit:

john
tn: John Lennon
var @sortname: "lennon, john"^^http://www.w3.org/2001/XMLSchema#string

# Shorter through prefix defintion:

%prefix xs http://www.w3.org/2001/XMLSchema#

john
tn: John Lennon
var @sortname: "lennon, john"^^xs:string

3.2.11. Topic Name with a Variant of datatype XML

AsTMa=

john
tn: John Lennon
var @markup: "<b>John Lennon</b>"^^http://www.w3.org/2001/XMLSchema#anyType

# Solution using a prefix omitted.

3.2.12. Topic Name with a Variant of datatype IRI

AsTMa=

# See 3.2.10: The AsTMa= processor is aware of commonly used URI protocols, like
# http, file, etc., so normally there is no need to qualify the strings and 
# and URIs:

john
tn: John Lennon
var @image: http://en.wikipedia.org/wiki/Image:Jk_beatles_john.jpg

# Explicit datatype:

john
tn: John Lennon
var @image: "http://en.wikipedia.org/wiki/Image:Jk_beatles_john.jpg"^^http://www.w3.org/2001/XMLSchema#anyURI

# Prefix solution omitted

3.2.13. Topic Name with a Variant of a non-TMDM datatype

AsTMa=

revolution-nine
tn: Revolution 9
var @number: "9"^^http://www.w3.org/2001/XMLSchema#integer

# Prefix solution omitted

3.3. Assigning Occurrences to a Topic

This section defines use cases for creating occurrences.

3.3.1. Occurrence of datatype String

AsTMa=

# Note: AsTMa= makes a difference between inline occurrences
# (like strings, integers etc.) and external occurrences, that
# are always URIs
# For inline occurrences AsTMa= uses the keyword "in".
# For external occurrences AsTMa= v2.0 uses the keyword "ex".
# For backward compatibilty with AsTMa= 1.3 it is also possible 
# to qualify an _external_ occurrence with the keyword "oc"

adayinthelife
in: I read the news today, oh boy

# AsTMa= handels this automatically as string. It's also possible to 
# make it more explicit:

adayinthelife
in: "I read the news today, oh boy"^^http://www.w3.org/2001/XMLSchema#string

# Prefix solution omitted

3.3.2. Typed Occurrence of datatype String - Using Item Identifiers

AsTMa=

adayinthelife
in (lyrics): I read the news today, oh boy

3.3.3. Typed Occurrence of datatype String - Using Subject Identifiers

AsTMa=

adayinthelife
in (i'http://psi.example.org/lyrics): I read the news today, oh boy

# Using a prefix:

%prefix ex i'http://psi.example.org/

in (ex:lyrics): I read the news today, oh boy

3.3.4. Scoped Occurrence of datatype String - Using Item Identifiers

AsTMa=

adayinthelife
in @en: I read the news today, oh boy

3.3.5. Scoped Occurrence of datatype String - Using Subject Identifiers

AsTMa=

adayinthelife
in @i'http://www.topicmaps.org/xtm/1.0/language.xtm#en: I read the news today, oh boy

# With prefix defintion:

%prefix xtm i'http://www.topicmaps.org/xtm/1.0/language.xtm#

adayinthelife
in @xtm:en: I read the news today, oh boy

3.3.6. Occurrence of datatype XML

AsTMa=

adayinthelife
in: "<html><head><title>A day in the life</title></head><body><p>I read the news today, oh boy</p></body></html>"^^http://www.w3.org/2001/XMLSchema#anyType

# Alternative: Breaking up the string using triple quotes
# Note that this would insert "\n"'s into the XML
    
adayinthelife
in: """<html>
<head>
<title>A day in the life</title>
</head>
<body>
<p>I read the news today, oh boy</p>
</body>
</html>"""^^http://www.w3.org/2001/XMLSchema#anyType


# Alternative: Using line continuation with the backslash at 
# the end of the line. The XML would then be in one line (no \n's inserted)
# Using the backslash can be done with simple quoted strings (" or ')
# and triple quoted strings (""" or ''')

adayinthelife
in: "<html>\
<head>\
<title>A day in the life</title>\
</head>\
<body>\
<p>I read the news today, oh boy</p>\
</body>\
</html>"^^http://www.w3.org/2001/XMLSchema#anyType

3.3.7. Occurrence of datatype IRI

AsTMa=

# As said AsTMa= distinguishes between external and internal occurrences
# External occurrences are automatically datatyped with 
# http://www.w3.org/2001/XMLSchema#anyURI
    
beatles
ex: http://beatles.com/
    
# AsTMa= v1.3 compatibility
beatles
oc: http://beatles.com/
    
# This is also be possible but is against our intention
beatles
in: "http://beatles.com/"^^http://www.w3.org/2001/XMLSchema#anyURI

3.3.8. Occurrence of a non-TMDM datatype

AsTMa=

pennylane
in: "2"^^http://www.w3.org/2001/XMLSchema#integer

3.4. Creating Associations

This sections defines use cases to create associations and association roles.

3.4.1. Creating an Association

AsTMa=

(created-by)
work: yesterday
creator: mccartney

# Possible: Defintion of an association template (useful if 
# the 'created-by' association occurs more than once
    
# Association template definition (take care of the [] brackets!)
[(created-by)
  work: http://astma.it.bond.edu.au/authoring/psi/1.0#left
  creator: http://astma.it.bond.edu.au/authoring/psi/1.0#right
]
    
# The URIs http://astma... are placeholders. The ...#left URI
# will be replaced by a topic that occurs at the far left and
# the right URI will be replaced by the topic at the right side
    
# Applying the association template:
    
yesterday created-by mccartney
    
# The effect of the "yesterday created-by mccartney" statement is
# the same as the association defintion in the first solution

3.4.2. Scoped Association

AsTMa=

@inofficial (created-by)
work: yesterday
creator: mccartney
    

# Using scope is also possible inside an association template:
[@inofficial (created-by)
  work: http://astma.it.bond.edu.au/authoring/psi/1.0#left
  creator: http://astma.it.bond.edu.au/authoring/psi/1.0#right
]
   
# Applying the association template looks the same as in 3.5.1

yesterday created-by mccartney

3.4.3. Untyped Association

AsTMa=

# In AsTMa= the empty type (indicated by "()") is 
# automatically the default type
()
work: yesterday
creator: mccartney
    
# Make it more explicit:
(i'http://psi.topicmaps.com/iso13250/association )
work: yesterday
creator: mccartney

3.4.4. Untyped Association Role

AsTMa=

# The star * indicates that an "anonymous" default topic
# should be created (or if a topic with the subject identifier
# http://psi.topicmaps.com/iso13250/association-role already
# exists this topic will be used)
    
(created-by)
* : yesterday
creator: mccartney

3.4.5. Supertype-Subtype relationship - Using Item Identifiers

AsTMa=

# AsTMa= has build-in an association template "subclasses" and
# the synonym "is-subclass-of" that creates the supertype-subtype
# association
# The term "subclass" is carried over from AsTMa= v1.3, maybe we'll 
# provide "subtypes" and "is-subtype-of" for AsTMa= v2.0 to be d'accord with 
# TMDM
    
song subclasses musical-work
    
song is-subclass-of musical-work
    
# The two solutions are equal with the explicit association
# defintion:
    
(i'http://psi.topicmaps.com/iso13250/supertype-subtype )
http://psi.topicmaps.com/iso13250/supertype : musical-work
http://psi.topicmaps.com/iso13250/subtype : song

3.4.6. Supertype-Subtype relationship - Using Subject Identifiers

AsTMa=

# Using the build-in association template
    
i'http://psi.example.org/song subclasses i'http://psi.example.org/musical-work
    
i'http://psi.example.org/song is-subclass-of i'http://psi.example.org/musical-work


# Equivalent association:
(i'http://psi.topicmaps.com/iso13250/supertype-subtype )
http://psi.topicmaps.com/iso13250/supertype : i'http://psi.example.org/musical-work
http://psi.topicmaps.com/iso13250/subtype : i'http://psi.example.org/song


# With prefix defintion:

%prefix ex i'http://psi.example.org/

ex:song subclasses ex:musical-work

3.5. Reification

3.5.1. Reification of a Topic Map

AsTMa=

# Reification has to be done with the "topicmap" directive:
    
%topicmap is-reified-by beatles-topicmap
    
beatles-topicmap
tn: Topic map about The Beatles
    
# The keyword "is-reified-by" is only used for better readability and
# can be omitted. Shorthand:
    
%topicmap beatles-topicmap
    
beatles-topicmap
tn: Topic map about The Beatles

3.5.2. Reification of a Topic Name

AsTMa=

# Note: You have to put the topic name value into
# quotes to reify a topic name. This has to be done
# to tell the AsTMa= processor where the topic name 
# value ends. This is also true for topic variants and
# occurrences

john
tn: "John Ono Lennon" is-reified-by name-of-john-lennon
    
# DON'T DO THIS:
# john
# tn: John Ono Lennon is-reified-by name-of-john-lennon
    
#    Result of the DON'T: Value of the topic name is 
#    "John Ono Lennon is-reified-by name-of-john-lennon"

# As shorthand "reified-by" can also be used:
john
tn: "John Ono Lennon" reified-by name-of-john-lennon

3.5.3. Reification of a Variant

AsTMa=

john
tn: John Lennon
var @sortname: "lennon, john" is-reified-by johns-sortname
    
# Explicit datatype:
john
tn: John Lennon
var @sortname: "lennon, john"^^http://www.w3.org/2001/XMLSchema#string is-reified-by johns-sortname

3.5.4. Reification of an Occurrence

AsTMa=

# For external occurrences no quotes are necessary
# because a space indicates the end of a URI

john
ex: http://johnlennon.com/ reified-by lennons-website
    
lennons-website
tn: Official website of John Lennon

3.5.5. Reification of an Association

AsTMa=

(partnership) is-reified-by lennon-mccartney
partner: lennon
partner: mccartney
    
lennon-mccartney
tn: Lennon / McCartney

3.5.6. Reification of an Association Role

AsTMa=
```
# Not possible with AsTMa= 
```
LTM

3.6. Comments

The CTM should support comments to annotate the topic map content.

3.6.1. Singleline Comment

AsTMa=
```
# This is a topic map about The Beatles
```
LTM

3.6.2. Multiline Comment

AsTMa=

# This is a topic map about The Beatles
#
# Authored by John Doe

3.6.3. Local comments????

AsTMa=

# Examples:

john # This creates a topic with the item identifier "john"

3.7. Medium sized topic map

To get an impression how a medium sized topic map in the various notations looks like, we define a topic map in the above mentioned problem domain.

AsTMa=

Note, that this solution would produce an other CXTM output than the XTM topic map. I tried to use subject identifiers as much as possible.

%version 2.0

%topicmap reified-by beatles-map

# Prefix definitions
%prefix music i'http://psi.example.org/music/
%prefix xtm   i'http://www.topicmaps.org/xtm/1.0/core.xtm#
%prefix lang  i'http://www.topicmaps.org/xtm/1.0/language.xtm#
%prefix astma http://astma.it.bond.edu.au/authoring/psi/1.0#

# Defintions of named association templates
# Named association templates are mainly used where the type
# of the association template is specified by a subject identifier

created-by = [(i'http://psi.example.org/created-by )
   work: astma:left
   i'http://purl.org/dc/elements/1.1/creator: astma:right
]

is-member-of = [(membership)
   member: astma:left
   group: astma:right
]

is-track-on = [(i'http://psi.test.org/assoc#istrackof)
               track: astma:left
               container: astma:right
              ]

beatles-map
  tn: Topic map about The Bealtes

membership
  tn: Membership
  tn @group: has member
  tn @member: is member of

partnership
  tn: Partnership

lyrics
  tn: lyrics
  in(description): The text of a song

album
  tn: album
  si: http://psi.test.org/music#album # Note: "si" is the keyword for subject identifier

music:musical-work
  tn: musical work

music:song subclasses music:musical-work
  tn: song
  tn @lang:de: Lied

music:instrumental subclasses music:musical-work
  tn: instrumental
  in (description): An instrumental is a musical work that is performed by instruments only.

description
  tn: description

website
  tn: website

partner:
  tn: partner

the-beatles
  tn: The Beatles
  var @xtm:sort: beatles, the
  si: http://psi.example.org/music/beatles/the%20beatles
  ex (website): http://thebeatles.com

# The four beatles
john is-a person is-member-of the-beatles
  tn: John Lennon
  var @xtm:sort: lennon, john
  si: http://psi.example.org/music/beatles/john

paul is-a person is-member-of the-beatles
  tn: Paul McCartney
  var@xtm:sort: mccartney, paul
  si: http://psi.example.org/music/beatles/paul

ringo is-a person is-member-of the-beatles
  tn: Ringo Starr
  var @xtm:sort: starr, ringo
  si: http://psi.example.org/music/beatles/ringo

george is-a person is-member-of the-beatles
  tn: George Harrison
  var @xtm:sort: harrison, george
  si: http://psi.example.org/music/beatles/george

# Creating the Lennon / McCartney association
(partnership) is-reified-by lennon-mccartney
partner: paul john

# The reifier of the association
lennon-mccartney
  tn: Lennon / McCartney

# The albums
sgt-pepper-album is-a album
  tn: Sgt. Pepper's Lonely Hearts Club Band
  si: http://psi.testing.org/beatles/album/sgtpepper

mmt-album is-a album
  tn: Magical Mystery Tour
  si: http://psi.testing.org/beatles/album/magicalmysterytour

# The songs

# Note, that a backslash indicates that the line is continued

adayinthelife is-a music:song created-by lennon-mccartney \
              is-track-on sgt-pepper-album
  tn: A day in the life
  in (length): 5:03
  in (lyrics): """\
I read the news today oh, boy
About a lucky man who made the grade
And though the news was rather sad
Well, I just had to laugh
I saw the photograph
He blew his mind out in a car 
[...]"""

flying is-a music:instrumental is-track-on mmt-album \
       created-by the-beatles
  tn: Flying
  in (length): 2:16

LTM

/*
 * Note that this TM was created automatically and may not look so nice
 * as it should do.
 */

@"utf-8" #VERSION "1.3"

/* ----------------- TOPIC MAP ----------------- */

#TOPICMAP ~ beatles-topic
[beatles-topic = "Topic map about The Beatles"]

/* ----------------- ONTOLOGY ------------------ */

/* ----------------- Topic Types --------------- */

[album = "album"
    @"http://psi.test.org/music#album"]
[instrumental = "instrumental"
    @"http://psi.example.org/music/instrumental"]
   {instrumental, description, [[An instrumental is a musical work that is performed by instruments only.]]}
[music-group]
[person = "person"
    @"http://psi.test.org/person"]
[song = "song"
      = "Lied" / id2
    @"http://psi.example.org/music/song"]

/* ----------------- Type Hierarchy ------------ */

id8( musical-work : id6, instrumental : id7 )
id8( musical-work : id6, song : id7 )

/* ----------------- Role Types ---------------- */

[group]
[id5]
[id6
    @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[id7
    @"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[id9
    @"http://purl.org/dc/elements/1.1/creator"]
[member]
[partner = "partner"]
[track]
[work]

/* ----------------- Association Types --------- */

[id3
    @"http://psi.test.org/assoc#istrackof"]
[id4
    @"http://psi.example.org/created-by"]
[id8
    @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[membership = "Membership"
            = "has member" / group
            = "is member of" / member]
[partnership = "partnership"]

/* ----------------- Occurrence Types ---------- */

[description = "description"]
[length = "length"]
[lyrics = "lyrics"
    @"http://psi.example.org/lyrics"]
   {lyrics, description, [[The text of a song]]}
[website = "website"]

/* ----------------- INSTANCES ----------------- */

/* ----------------- Topics -------------------- */

/* -- TT: album -- */
[mmt-album : album = "Magical Mystery Tour"
    @"http://psi.testing.org/beatles/album/magicalmysterytour"]
[sgtpepper-album : album = "Sgt. Pepper's Lonely Hearts Club Band"
    @"http://psi.testing.org/beatles/album/sgtpepper"]

/* -- TT: instrumental -- */
[flying : instrumental = "Fyling"]
   {flying, length, [[2:16]]}

/* -- TT: music-group -- */
[thebeatles : music-group = "The Beatles"; "beatles, the"
    @"http://psi.example.org/music/beatles/the%20beatles"]
   {thebeatles, website, "http://thebeatles.com"}

/* -- TT: person -- */
[george : person = "George Harrison"; "harrison, george"
    @"http://psi.example.org/music/beatles/george"]
[john : person = "John Lennon"; "lennon, john"
    @"http://psi.example.org/music/beatles/john"]
[paul : person = "Paul McCartney"; "mccartney, paul"
    @"http://psi.example.org/music/beatles/paul"]
[ringo : person = "Ringo Starr"; "starr, ringo"
    @"http://psi.example.org/music/beatles/ringo"]

/* -- TT: song -- */
[adayinthelife : song = "A day in the life"]
   {adayinthelife, length, [[5:03]]}
   {adayinthelife, lyrics, [[I read the news today oh, boy
About a lucky man who made the grade
And though the news was rather sad
Well, I just had to laugh
I saw the photograph
He blew his mind out in a car 
[...\u00005D
    ]]}

/* -- TT: (untyped) -- */
[id1
    @"http://www.topicmaps.org/xtm/1.0/core.xtm#sort"]
[id2
    @"http://www.topicmaps.org/xtm/1.0/language.xtm#de"]
[lennon-mccartney-reifier = "Lennon / McCartney"]
[musical-work = "Musical work"
    @"http://psi.example.org/music/muscial-work"]

/* ----------------- Associations -------------- */

/* -- AT: id3 */
id3( mmt-album : id5, flying : track )
id3( sgtpepper-album : id5, adayinthelife : track )

/* -- AT: id4 */
id4( lennon-mccartney-reifier : id9, adayinthelife : work )
id4( thebeatles : id9, flying : work )

/* -- AT: membership */
membership( thebeatles : group, george : member )
membership( thebeatles : group, john : member )
membership( thebeatles : group, paul : member )
membership( thebeatles : group, ringo : member )

/* -- AT: partnership */
partnership( john : partner, paul : partner ) ~ lennon-mccartney-reifier

CTM - Use Case Solutions

Lars Heuer

Gabriel Hopmans

Sam Oh

1. Status of this Document

2. Introduction

3. Use Case Solutions

3.1. Creating Topics

3.1.1. Topic with an Item Identifier

3.1.2. Typed Topic - Using Item Identifiers

3.1.3. Typed Topic - Using Subject Identifiers

3.1.4. Multi Typed Topic - Using Item Identifiers

3.1.5. Multi Typed Topic - Using Subject Identifiers

3.2. Assigning Topic Names to a Topic

3.2.1. Topic with an Item Identifier and a Topic Name

3.2.2. Topic with a Subject Identifier and a Topic Name

3.2.3. Topic with a Subject Locator and a Topic Name

3.2.4. Typed Topic Name - Using Item Identifiers

3.2.5. Typed Topic Name - Using Subject Identifiers

3.2.6. Scoped Topic Name - Using Item Identifiers

3.2.7. Scoped Topic Name - Using Subject Identifiers

3.2.8. Multi Scoped Topic Name

3.2.9. Typed and Scoped Topic Name

3.2.10. Topic Name with a Variant of datatype String

3.2.11. Topic Name with a Variant of datatype XML

3.2.12. Topic Name with a Variant of datatype IRI

3.2.13. Topic Name with a Variant of a non-TMDM datatype

3.3. Assigning Occurrences to a Topic

3.3.1. Occurrence of datatype String

3.3.2. Typed Occurrence of datatype String - Using Item Identifiers

3.3.3. Typed Occurrence of datatype String - Using Subject Identifiers

3.3.4. Scoped Occurrence of datatype String - Using Item Identifiers

3.3.5. Scoped Occurrence of datatype String - Using Subject Identifiers

3.3.6. Occurrence of datatype XML

3.3.7. Occurrence of datatype IRI

3.3.8. Occurrence of a non-TMDM datatype

3.4. Creating Associations

3.4.1. Creating an Association

3.4.2. Scoped Association

3.4.3. Untyped Association

3.4.4. Untyped Association Role

3.4.5. Supertype-Subtype relationship - Using Item Identifiers

3.4.6. Supertype-Subtype relationship - Using Subject Identifiers

3.5. Reification

3.5.1. Reification of a Topic Map

3.5.2. Reification of a Topic Name

3.5.3. Reification of a Variant

3.5.4. Reification of an Occurrence

3.5.5. Reification of an Association

3.5.6. Reification of an Association Role

3.6. Comments

3.6.1. Singleline Comment

3.6.2. Multiline Comment

3.6.3. Local comments????

3.7. Medium sized topic map