ISO/IEC JTC 1/SC 34N0880rev

ISO/IEC JTC 1/SC 34

Information Technology --
Document Description and Processing Languages

TITLE:	Draft 13250-6 Topic Maps -- Compact Syntax
SOURCE:	Mr. Lars Heuer; Mr. Gabriel Hopmans; Dr. Sam Gyun Oh; Mr. Steve Pepper
PROJECT:	WD 13250-6: Information technology - Topic Maps - Compact syntax
PROJECT EDITOR:	Mr. Lars Heuer; Mr. Gabriel Hopmans; Dr. Sam Gyun Oh
STATUS:	Draft
ACTION:	Review in preparation for WG3 meeting
DATE:	2007-07-28
DISTRIBUTION:	SC34 and Liaisons
REPLY TO:	Dr. James David Mason (ISO/IEC JTC 1/SC 34 Chairman) Y-12 National Security Complex Bldg. 9113, M.S. 8208 Oak Ridge, TN 37831-8208 U.S.A. Telephone: +1 865 574-6973 Facsimile: +1 865 574-1896 Network: [email protected] http://www.y12.doe.gov/sgml/sc34/ ftp://ftp.y12.doe.gov/pub/sgml/sc34/ Mr. G. Ken Holman (ISO/IEC JTC 1/SC 34 Secretariat - Standards Council of Canada) Crane Softwrights Ltd. Box 266, Kars, ON K0A-2E0 CANADA Telephone: +1 613 489-0999 Facsimile: +1 613 489-0995 Network: [email protected] http://www.jtc1sc34.org

Topic Maps — Compact Syntax

Contents

Foreword

ISO (the International Organization for Standardization) and IEC (the International Electrotechnical Commission) form the specialized system for worldwide standardization. National bodies that are members of ISO or IEC participate in the development of International Standards through technical committees established by the respective organization to deal with particular fields of technical activity. ISO and IEC technical committees collaborate in fields of mutual interest. Other international organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.

International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.

ISO/IEC 13250-6 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information Technology, Subcommittee SC 34, Document Description and Processing Languages.

ISO/IEC 13250 consists of the following parts, under the general title Topic Maps:

• Part 1: Overview and Basic Concepts
• Part 2: Data Model
• Part 3: XML Syntax
• Part 4: Canonicalization
• Part 5: Reference Model
• Part 6: Compact Syntax
• Part 7: Graphical Notation

Introduction

CTM (Compact Topic Maps) is a text-based notation for representing topic maps. It provides a simple, lightweight notation that complements the existing XML-based interchange syntax described in [XTM] and can be used for

• manually authoring topic maps;

• providing human-readable examples in documents;

• serving as a common syntactic basis for TMCL and TMQL.

The principal design criteria of CTM are compactness, ease of human authoring, maximum readability, and comprehensiveness rather than completeness. CTM supports all constructs of the [TMDM], except item identifiers on constructs that are not topics.

Since CTM is not designed as interchange syntax, care should be taken when using CTM as a basis for interchanging topic maps.

This part of ISO/IEC13250 should be read in conjunction with [TMDM] since the interpretation of the CTM syntax is defined through a mapping from the syntax to the data model there defined.

Topic Maps — Compact Syntax

1 Scope

This part of ISO/IEC13250 defines a text-based notation for representing instances of the data model defined in [TMDM]. It also defines a mapping from this notation to the data model. The syntax is defined through an EBNF grammar.

2 Normative references

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

Unicode, The Unicode Standard, Version 5.0.0, The Unicode Consortium, Reading, Massachusetts, USA, Addison-Wesley Developer's Press, 2007, ISBN 0-321-48091-0, http://www.unicode.org/versions/Unicode5.0.0/

XML 1.0, Extensible Markup Language (XML) 1.0, W3C, Third Edition, W3C Recommendation, 04 February 2004, http://www.w3.org/TR/REC-xml/

TMDM, ISO 13250-2 Topic Maps — Data Model, ISO, 2006, Lars Marius Garshol, Graham Moore, http://www.isotopicmaps.org/sam/sam-model/

XTM, ISO 13250-3 Topic Maps — XML Syntax, ISO, 2006, http://www.isotopicmaps.org/sam/sam-xtm/

XSDT, XML Schema Part 2: Datatypes Second Edition, W3C, W3C Recommendation, 28 October 2004, http://www.w3.org/TR/xmlschema-2/

RFC3986, RFC 3986 - Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, 2005, http://www.ietf.org/rfc/rfc3986

RFC3987, RFC3987 - Internationalized Resource Identifiers (IRIs), M. Duerst, M. Suignard, 2005, http://www.ietf.org/rfc/rfc3987.txt

3 Syntax description

3.1 About the syntax

The acronym CTM is often used to refer to the syntax defined in this part of ISO/IEC13250. Its full name is Compact Topic Maps Syntax. The namespace for the CTM syntax is http://www.topicmaps.org/ctm/.

A CTM document is a text document that conforms to the CTM syntax. This clause defines the syntax of CTM documents using an EBNF grammar based on the notation described in [XML 1.0], and their semantics using prose describing the mapping from CTM documents to [TMDM]. The full EBNF can be found in Annex A.

3.2 Deserialization

The process of exporting a topic map from an implementation's internal representation of the data model to an instance of a Topic Maps syntax is known as serialization. The opposite process, deserialization, is the process of building an instance of an implementation's internal representation of the data model from an instance of a Topic Maps syntax.

This clause defines how instances of the CTM syntax are deserialized into instances of the data model defined in [TMDM]. Serialization is only implicitly defined, but implementations should guarantee that for any data model instance the CTM serialization produced by the implementation should when deserialized to a new data model instance produce one that has the same canonicalization as the original data model instance, according to [ISO 13250-4].

The input to the deserialization process is:

• A CTM document.

• An absolute IRI. This is the IRI from which the CTM document was retrieved, known as the document IRI. This IRI shall always be provided, as it is necessary in order to assign the item identifiers of the topic items created during deserialization. If the CTM document was not read from any particular IRI the application is responsible for providing an IRI considered suitable.

Deserialization is performed by processing each component of the document in document order. Components are defined in terms of text that matches a syntactic variable of the EBNF. For each component encountered the operations specified in the clause for the corresponding syntactic variable are performed.

Whenever a new information item is created, those of its properties which have set values are initialized to the empty set; all other properties are initialized to null.

Each CTM processor must be aware of the following prefixes

xs

http://www.w3.org/2001/XMLSchema#

This is the namespace for the XML Schema Datatypes.

ctm

http://www.topicmaps.org/ctm/

This is the namespace for this part of ISO/IEC13250

3.3 Common syntactical constructs

3.3.1 Comments

Comments are fragments of the character stream which are ignored by any CTM processor. Comments are allowed where whitespace characters are allowed. Comments are introduced by a hash (#) and reach until the end of the current line, or until the end of the text stream, whatever comes first.

3.3.2 Line Continuations

Two or more physical lines may be joined into logical lines using backslash characters (\): When a physical line ends in a backslash, it is joined with the following forming a single logical line. The backslash character and the end-of-line character are not part of the resulting line.

Neither comments nor tokens (except for strings) can be continued.

3.3.3 Creating IRIs from strings

To create an IRI from a string unescape the string by replacing %HH escape sequences with the characters they represent, and decode the resulting character sequence from UTF-8 to a sequence of abstract Unicode characters. The resulting string is turned into an absolute IRI by resolving it against the document IRI.

3.3.4 Creating IRIs from QNames

QNames are used to abbreviate IRIs. They are declared as follows:

A QName a causes a locator to be created. The IRI to which the prefix is bound to, and the local part are concatenated. The result of such process is always an absolute IRI.

The prefix should have been bound to an IRI as specified in 3.12.3; if the prefix is unbound, an error is flagged.

3.3.5 IRI References

IRI references are either QNames or absolute IRIs. They are interchangeable: Everywhere where an IRI is used a QName can be used (if the prefix was previously defined).

3.3.6 Topic References

Topics are referenced by an item identifier, a subject identifier, or a subject locator.

During deserialization, one topic item is created for each topic-ref.

If the topic-ref is an identifier, a locator is created by concatenating the document IRI, a # character, and the value of the identifier. The locator is added to the [item identifiers] property of the topic.

If the topic-ref is specified by a subject identifier, a locator is created and added to the [subject identifiers] property of the topic.

If the topic-ref is specified by a subject locator, a locator is created (the introducing = is not part of the locator) and added to the [subject locators] property of the topic.

If the topic-ref is specified by a wildcard, a locator is created. The locator should use the document locator as base with a concanated # and a random identifier. That locator should not be equal to any other subject identifier, subject locator or item identifier contained in the topic map. The unique, newly created locator is added to the [item identifiers] property of the topic. This operation should not cause any merging operation.

If the topic-ref is specified by a named-wildcard, at the first occurrence of such construct a unique locator is created which shall use the document locator concatenated with # and a random identifier. This locator is added to the [item identifiers] property of the newly created topic. This operation should not cause any merging operation. If the named-wildcard is used again, the same topic is reused.

If the created topic item is equal to another topic item (c.f. [TMDM] 5.3); the two topic items are merged according to the procedure given in [TMDM].

# A topic referenced by the subject locator "http://www.isotopicmaps.org/"
= http://www.isotopicmaps.org/

# A topic referenced by a subject identifier
http://psi.example.org/the-beatles/John

# A topic with a unique, randomly created item identifier, it is not possible to refer to
# this topic inside the CTM document.
* - "A topic"


# A topic with a unique, randomly created item identifier with the possibility to refer 
# to it again
*foo - "A new, unique topic"

*foo isa subject # *foo refers to the same topic which was created by the first "*foo" occurrence

3.3.7 Scope

The scope construct is used to assign a scope to an information item.

Each topic-ref element is processed according to the procedure described in 3.3.6. These topic items are gathered into a set that is assigned as the value of the [scope] property of the Topic Maps construct being processed.

3.3.8 Reifier

The reifier construct is used to refer from the Topic Maps construct on which it appears to the topic reifying that construct. The reference is a topic-ref as described in 3.3.6

During deserialization the topic-ref is resolved into a topic item following the procedure in 3.3.6. The topic item is set as the value of the [reifier] property of the Topic Maps construct being processed.

3.3.9 Type

The type construct is used to assign a type to the Topic Maps construct where this construct occurs. The type is always a topic, indicated by the topic-ref.

During deserialization the topic-ref produces a topic item following the procedure in 3.3.6, which is set as the value of the [type] property of the information item being processed.

3.4 Topic Map

The topicmap component acts as a container for the topic map but has no further significance. It is declared as follows:

3.4.1 Topic Map Reifier

During deserialization the topic is resolved following the procedure in 3.5 and the topic item is set as the value of the [reifier] property of the topic map.

# Fragment A
~ tm-reifier - "My topic map"


# Fragment B
~ tm-reifier

tm-reifier
- "My topic map"

3.5 Topics

If additional subject identifiers or subject locators are provided, a locator is created for each of them according to the procedure described in 3.3.6 and added to the [subject identifiers] ( respectively [subject locators] property of the topic. If this procedure makes the topic equal to another topic item (c.f. [TMDM] 5.3); the two topic items are merged according to the procedure given in [TMDM].

If the topic declaration contains template invocations 3.11, the first argument is automatically bound to the the produced topic item.

john-lennon

lennon . mccartney . harrison . starr . # Four topics in one line

# A topic defined by its subject locator
= http://www.isotopicmaps.org/ - "The ISO Topic Maps website"

# A topic defined by a subject identifier
http://psi.example.org/the-beatles/John
- "John Lennon"

# A topic with a local identifier and a subject identifier
john http://psi.example.org/the-beatles/John
- "John Lennon"
      

3.6 Associations

During deserialization an association item is created for each association and added to the [associations] property of the topic map item. The [type] property of the association is set to the topic produced by the assoc-type as decribed in 3.3.9.

During deserialization an association role item is created for each role-type / player pair. The role item is added to the [roles] property of the association item.

is-member-of(group: The-Beatles, member: john)

# Declaration of an association which refers to topics by their subject identifiers
is-member-of(http://psi.example.org/group : http://psi.example.org/the-beatles ,
             http://psi.example.org/member : http://psi.example.org/john )


%prefix tm http://psi.topicmaps.org/iso13250/model/

tm:supertype-subtype(tm:subtype: woman, tm:supertype: human)

3.7 Occurrences

During deserialization the occurrence construct causes an occurrence item to be created, and added to the [occurrences] property of the topic item created by the procedure decribed in 3.5.

paul-mccartney
birthday: 1942-02-18    # Occurrence of type "birthday" with the value "1942-02-18" and datatype "xs:date"

# Now a difficult to read (but valid) example
# Topic with identifier "paul-mccartney", occurrence of type "birthday", default name in
# scope "formal" and an occurrence of type "website"
paul-mccartney birthday: 1942-02-18 - "Sir Paul McCartney" @formal website: http://www.paulmccartney.com/
      

3.8 Names

The name construct is used to add a topic name to a topic. It is declared as follows:

During deserialization the name construct causes a topic name item to be created, and added to the [topic names] property of the topic item created by the procedure decribed in 3.5.

If the type is not specified, the [type] property of the topic name item is set to the topic item whose [subject identifiers] property contains http://psi.topicmaps.org/iso13250/model/topic-name; if no such topic item exists, one is created.

paul-mccartney - "Paul McCartney" # Name with the default name type, colon omitted

paul-mccartney -: "Paul McCartney" # Name with the default name type, colon provided

john-lennon - "John Lennon"    # Default name
- fullname: "John Winston Lennon"    # Name of type "fullname"
- surname "Lennon"    # Name of type "surname", colon omitted
      

3.9 Variants

The variant construct is used to add a variant name to a topic name. It is declared as follows:

During deserialization the variant construct causes a variant item to be created and added to the [variants] property of the topic name item created by the procedure described in 3.8. After the scope has been processed, the topics in the [scope] property of the topic name item created by the parent name construct are added to the [scope] property of the variant name item.

%prefix tm http://psi.topicmaps.org/iso13250/model/

# Topic with name "John Lennon" which has a variant which represents a sort name
john - "John Lennon" ("lennon, john" @tm:sort)
    

3.10 Templates

Templates are containers for arbitrary Topic Maps constructs and a subset of directives specified by this part of ISO/IEC13250. The template body consists of ordinary topics and associations with the additional possibility to replace topic references (3.3.6) and literals (3.13) with variables.

Template declarations are defined as follows:

Everywhere, where a topic-ref or a literal is allowed, a variable is allowed.

The declaration of a template does not change the topic map content until it has been used within a template invocation (3.11).

If a template with the same identifier exists, an error is flagged.

If a template contains a prefix directive (3.12.3), the declared prefix is only valid within the template body. The prefixes, which were declared outside the template are accessible in the template body.

If a named-wildcard is used inside the template body, this named-wildcard is accessible only in the template body. A named-wildcard causes the creation of a topic each time the template is invoked.

def is-a($instance, $type)
  %prefix tm http://psi.topicmaps.org/iso13250/model/
  tm:type-instance(tm:instance: $instance, tm:type: $type)
end

# An error is flagged, because the prefix "tm" is not specified.
tm:type-instance(tm:instance: mccartney, tm:type: person)


%prefix wiki http://en.wikipedia.org/wiki/

def is-beatle($member)
  # Accessing the prefix "wiki" works, because it was defined in the document's scope
  is-member-of(member: $member, group: wiki:The-Beatles)
end

is-beatle(wiki:John_Lennon)
        

# Declaration of a template
def born($left, $right, $in)

    $left isa person
    birthday: $right

    born-in(person : $left, birthplace : $in)
end

# Invocation of the template
mccartney born(1942-06-12, Liverpool)


# The same effect would have been the following declaration:

mccartney isa person
birthday: 1942-06-12

born-in(person: mccartney, birthplace: Liverpool)

  

If the template name is already used by another template declaration, an error is flagged.

Template names and topic identifiers do not share the same namespace. If a template with name A exists, it is still possible to declare a topic with the identifier A.

The following templates are predefined:

isa

This template creates a type-instance relationship between two topics (c.f. [TMDM] 7.2).

def isa($instance, $type) %prefix tm http://psi.topicmaps.org/iso13250/model/ tm:type-instance(tm:instance: $instance, tm:type: $type) end

iko

The is kind of template creates a supertype-subtype relationship between two topics (c.f. [TMDM] 7.3).

def iko($sub, $super) %prefix tm http://psi.topicmaps.org/iso13250/model/ tm:supertype-subtype(tm:subtype: $sub, tm:supertype: $super) end

3.11 Template Invocation

A template invocation causes the statements of the template to be added to the topic map where the variables in the statements are replaced by the specified arguments.

If the template was not previously defined, an error is flagged.

If the template-reference is a qname and the prefix was not created by the procedure described in 3.12.6, an error is flagged.

If not all variables are bound, an error is flagged.

# Valid template invocations
mccartney isa person
          plays-for(The-Beatles, piano)
          
mccartney has-shoesize 42

# Template invocations outside of topic declarations
plays-for(john, The-Beatles, guitar)

has-shoesize(john, 45)
      

3.12 Directives

Directives are used to define the environment for a CTM processor and are divided into normative directives and non-normative directives (the user directives).

Each directive shall occur in a line of its own. Only a comment is allowed in the the same line.

3.12.1 Encoding Directive

The encoding directive specifies the character encoding used by the document.

If the encoding declaration is omitted, UTF-8 encoding is assumed. The name of the encoding should be given as a string in the form recommended by [XML 1.0].

If the encoding is provided, it shall occur in the first line of the document.

%encoding "Shift-JIS"
        

3.12.2 Version Directive

The version directive states the version number of the CTM syntax, which is currently "1.0". It is declared as follows:

The version directive tells the parser which version of the CTM syntax to use during deserialization. Currently the only legal version is 1.0, as defined by this part of ISO/IEC13250.

While the version directive may be omitted, this part of ISO/IEC13250 recommends its usage for future compatibility.

If the version directive is provided, it should occur after the encoding directive (second line of the document). If the encoding directive is omitted, the version directive shall occur in the first line of the document.

3.12.3 Prefix Directive

The prefix directive is used to associate an IRI with an identifier. It is declared as follows:

During deserialization the prefix component binds the identifier to the IRI (fragment).

If the identifier is already bound, an error is flagged unless the identifier is bound to one and the same IRI.

The iri-fragment may not be a valid IRI but the concatenation of the iri-fragment and the local part of a QName should produce a valid IRI, otherwise an error should be flagged.

%prefix wiki http://en.wikipedia.org/wiki/

# QNames can be used for subject identifiers / subject locators and as value for occurrences / variants
wiki:John_Lennon
- "John Lennon"
description: wiki:John_Lennon # Generates an occurrence of type "description" with the
                              # value "http://www.wikipedia.org/wiki/John_Lennon" with
                              # the datatype "http://www.w3.org/2001/XMLSchema#anyURI"

# Here an IRI fragment is bound to "isbn"
%prefix isbn urn:isbn:

isbn:370264850X # Creates a topic with the subject identifier urn:isbn:370264850X
- "Das kleine Ich bin Ich".  # A worthwhile book to read :)
        

3.12.4 Include Directive

The include directive is used to include another CTM document into the CTM file. The other document is referenced by an IRI.

The referenced document should use CTM syntax, otherwise an error is flagged.

During deserialization the include component causes the referenced topic map to be immediately deserialized into a data model instance. The new data model instance (B) is then merged into the current one (A) by

• Iterating through all topic item in B's [topics] property and identifying those topics which contain a locator in their [item identifiers] property which starts with the referenced document locator.

  For each of the identified topics a locator is created by subtracting the referenced document locator from the item identifier which start with the referenced document locator.

  The result of that subtraction is concatenated with the document locator of A. The result is an absolute locator which is added to the [item identifiers] property of the topic.

• Adding all topic items in B's [topics] property to A's [topics] property.

• Adding all association items in B's [associations] property to A's [associations] property.

3.12.5 Mergemap Directive

The mergemap directive is used to merge an external topic map into the topic map produced by deserializing the CTM topic map.

This directive is declared as follows:

The topic map to be merged can be in any syntax, which must be declared (using the notation component) if it is not CTM.

This part of ISO/IEC13250 uses the following identifiers for Topic Maps syntaxes:

http://www.topicmaps.org/ctm/

This is the namespace for CTM.

http://www.topicmaps.org/xtm/

This is the namespace for XML Topic Maps.

During deserialization the mergemap component causes the referenced topic map to be immediately deserialized into a data model instance. The new data model instance (B) is then merged into the current one (A) by

• Adding all topic items in B's [topics] property to A's [topics] property.

• Adding all association items in B's [associations] property to A's [associations] property.

3.12.6 Template Import Directive

The template.import directive is used to make templates from another CTM document usable in the current document.

A selective-import causes the import of the specified templates into the local namespace (if the wildcard (*) is used, all templates are imported).

After the import the templates can be invoked if they have been specified in the current CTM document.

A namespace-import causes a prefix to be created. After the creation of the prefix, the templates can be accessed with the QName notation (identifier:template-name). If the prefix is already in use, an error is flagged.

%from http://example.org/my-template-lib.ctm import is-member-of, \
      plays

mccartney is-member-of The-Beatles
          plays piano


# The same as above, using the prefix
%import http://example.org/my-template-lib.ctm as my-lib
        
mccartney my-lib:is-member-of The-Beatles
          my-lib:plays piano

3.12.7 Stop Directive

For debugging purposes, the stop directive is introduced as follows:

This directive causes the CTM processor to stop processing the document any further.

After the stop directive arbitrary text may occur which is not processed.

mccartney is-member-of The-Beatles
          plays piano
          
%stop

# The following topic declaration is ignored by the CTM processor
john isa person
- "John Lennon"

This text is also ignored
      

3.12.8 User Directives

User directives are directives which may be supported by a CTM processor. In constrast to the normative directives a CTM processor may ignore them.

Every user directive is introduced by %x- and reach until the end of the line.

%x-log on

mccartney isa person

%x-log off

%x-db-query "SELECT ...." | mysql | awk ’...’ |

A compatible CTM processor may issue a warning if it finds an unsupported user directive but should not stop to read the CTM document.

This part of ISO/IEC13250 does neither specify how the user-directive is executed nor how the command is further processed (additional split ups may be necessary).

3.13 Literals

A literal is a string value with an optional datatype.

For convenience, this part of ISO/IEC13250 provides the identification of integers, decimals, IRIs, dates and dateTime values natively.

This part of ISO/IEC13250 associates the following implicit datatypes to the above mentioned literals

iri-ref

http://www.w3.org/2001/XMLSchema#anyURI

If the iri-ref is a QName, the QName converted into an IRI by the procedure described in 3.3.4

decimal

http://www.w3.org/2001/XMLSchema#decimal

integer

http://www.w3.org/2001/XMLSchema#integer

null

http://www.topicmaps.org/ctm/null

date

http://www.w3.org/2001/XMLSchema#date

date-time

http://www.w3.org/2001/XMLSchema#dateTime

string

http://www.w3.org/2001/XMLSchema#string

Any literal can be expressed by representing the value as a string and appending the datatype qualifier (^^) and a iri-ref which indicates the datatype.

If a literal occurs inside of an occurrence 3.7 declaration, the occurrence [value] property is set to the value of the literal and the occurrence [datatype] property is set to the datatype of the literal.

If a literal occurs inside of a variant 3.9 declaration, the variant [value] property is set to the value of the literal and the variant [datatype] property is set to the datatype of the literal.

"42"^^xs:integer   # This declaration has the same effect as just writing 42
"12-22"^^xs:gMonthDay
      

3.13.1 Escape Syntax

The following escape sequences can be used inside strings:

\u HEX HEX HEX HEX

@@@TODO: Escape syntax for unicode characters

\"

@@@TODO: Escape syntax for double quotes

\\

@@@TODO: Escape syntax for backslash

A Syntax (informative)

Core Syntax

Bibliography

ISO/IEC 13250:2003, Topic Maps, 2003, http://www.y12.doe.gov/sgml/sc34/document/0322_files/iso13250-2nd-ed-v2.pdf

ISO 13250-4, Topic Maps — Canonicalization, http://www.isotopicmaps.org/sam/cxtm/