The HyTime Topic Maps (HyTM) Syntax 1.0

2.3 The topname architectural form

The HyTM topname architectural form is used to group together a set of base names, display names and sorting rules that apply to a topic within a specific scope. A topic may have zero or more sets of name characteristics (topic names) assigned to it.

The HyTM syntax distinguishes between three kinds of topic name: base name (basename), display name (dispname) and name used as sort key (sortname). At least one base name must be specified for each topic name group. If display names are to be associated with a set of base names they must follow the last of the base names and precede any names used as a sort key.

The topname architectural form is declared as follows:

<!element topname               -- Topic name -- 
                                -- ISO 13250: Clause 5.2.2-- 
          O O (basename+, dispname*, sortname* ) 
                                -- If dispnames or sortnames are not 
                                   specified, applications use basenames 
                                   for display and sorting purposes. --    > 
<!attlist topname 
                    scope       -- Scope -- 
                                -- Reference to a set of themes (topic 
                                   links) to be added to the scopes of the 
                                   name characteristics specified by the 
                                   contained basename, dispname, and 
                                   sortname elements. Scopes are sets of 
                                   themes that collectively define the 
                                   limited context within which 
                                   characteristics are validly applicable 
                                   to the topic. -- 
                    CDATA       -- Reference -- 
                                -- Reftype: topic+ -- 
                    #IMPLIED    -- Default: No themes are added via this attribute. -- >

The optional scope attribute can be used to identify the set of topics that indicate the contexts (areas of validity) in which this set of topic names is valid. After having all the added themes defined by the addthms attribute of the containing topicmap conformant element together with any assigned to topname conformant elements using an addthms element that references this topic map and those of the parent topic conformant element added to the set, these scoping topics are inherited by all children of the topname conformant element. 

Issue (HyTM-13250-no-scope):

This is the first case in ISO 13250 where a claim is made that if no scope attribute is provided for a particular element type it is "unconstrained". The wording of the subsequent text implies that any themes added by an addthms element (or attribute) only apply if the element has a scope attribute, which can be an empty string. Yet this ruling seems to contradict that given for addthms in 5.4 (third bullet) and Note 34 of clause 5.2.2, which states that such elements can be used to differentiate between topics without scope attributes. In addition, the comment associated with the addthems attribute clearly assigns these themes to the topic name element rather than its children. If "unconstrained" means "having no locally defined or inherited scoping attributes" the above text needs to be extended to allow for this state.

2.4 The basename, dispname and sortname architectural forms

The HyTM basename architectural form is used to assign one or more topic names to the topic created by the topic element that contains the topname it forms part of. The contents of the basename conformant element, which must form a string with no embedded markup, provide the [value] property of a SAM Topic Name item.

Note: More than one base name may be needed for a topic to allow the topic to be used by different linguistic communities.

The HyTM dispname and sortname architectural forms can optionally be used to create SAM Variant items that are associated with each of the Topic Name items created by the presence of basename conformant elements within the same topname conformant element. The displayable forms of the name created by dispname conformant elements can either contain a string of displayable data, or a topic map bridging (TMBrid) conformant element whose structured contents defines a displayable form of data. This can include data that is in a notation other than HyTime/SGML/XML providing that the notation used is identified using the HyTime defined notation common attribute, or can consist of simply a reference to an external data source. The contents of sortname conformant element, which must consist of a string of characters without embedded markup, can be used to indicate the order in which different sets of topic names are to be sorted when listing currently defined names. For example, an entry whose base name is Henry VIII could be assigned a sort name of Henry8 to ensure it is correctly sorted.

Note: The contents of the basename element provide default text for displaying and for sorting if no dispname or sortname conformant element is provided within the same topname conformant element.

HyTM does not permit two distinct subjects (topics with the same identity) to have the same name characteristics within exactly the same scope (this is known as the "topic naming constraint"). When topic maps are processed each distinct set of themes that serves as a scope constitutes a namespace in which no two subjects can have the same name. If a situation in which multiple topic conformant elements with the same name characteristics within the same scope is detected they must be merged.

Issue (HyTM-13250-notation-common-attribute):

ISO 13250 requires the use of the notation common attribute for specifying alternative notations for dispname entries, even though this attribute is not listed in the list of HyTime common attributes that apply to topic maps. Should it be added to the list of common attributes? Do we need this restriction for SAM conformance? What is the link, if any, between the value assigned to the notation attribute and the MIME type of XML references to external entities?

These architectural forms are declared as follows:

<!element (basename | sortname) -- Base name or Name to be used as sort key -- 
          - O (#PCDATA)         -- String to be used as name/sorting sequence -- > 
<!element dispname              -- Displayable form of name -- 
          - O (#PCDATA|TMBrid)* -- String (or notation data embedded within a TMBrid 
                                   conformant element) to be displayed as name -- >        
<!attlist ( basename | sortname | dispname)            
                    scope       -- Scope -- 
                                -- References to a set of themes (topic 
                                   links) to be added to the scope of the 
                                   name characteristic specified in the 
                                   content. -- 
                    CDATA       -- Reference -- 
                                -- Reftype: topic+ -- 
                    #IMPLIED    -- Default: No themes are added via this attribute. --  >

The optional scope attribute can be used to identify the set of topics that indicate the contexts in which this particular name is valid when it differs from the set applied to the parent topname conformant element. During deserialization each scoping topic, including those inherited from parent elements, is related to the Topic Name or Variant item through a scope connection.

2.5 The occurs architectural form

The HyTM occurs architectural form is used to define elements that reference occurrences of the subject  identified and named by its parent topic conformant element. It contains a set of one or more HyTime location addresses, which are specified using HyTime conformant elements whose contents allow one or more information resource components to be identified.

Note: HyTM imposes no constraints on the information objects that can be specified as occurrences of topics, nor on the addressing notations used to reference such occurrences. In particular, HyTime location addresses can identify spans of data, sets of elements, the contents of attributes and subtrees within a document. The locations can be specified using queries, natural language or structured markup. Not all HyTime locations are electronically resolvable. The same information resource components can be addressed in more than one way. No attempt is made to identify whether or not two HyTime location addresses refer to the same set of objects.

During deserialization each occurs conformant element generates a SAM Occurrence information item.

The occurs architectural form is declared as follows:

<!element occurs                -- Topic occurrence --
                                -- ISO 13250: Clause 5.2.3 --
          - O (%loc;)* >
<!attlist occurs    scope       -- Scope -- 
                                -- Reference to themes that are added to 
                                   the scope within which the occurrences 
                                   are applicable to the topic 
                                   characterized by the containing topic link.-- 
                    CDATA       -- Reference -- 
                                -- Reftype: topic+ -- 
                    #IMPLIED    -- Default: No themes are added to the scope 
                                   by means of this attribute. -- 
                    occrl       -- Occurrence role name -- 
                    NAME        -- Note: Not displayed for the topic map 
                                         user if the topic referenced by the 
                                         type attribute has displayable 
                                         characteristics within the user's scope. -- 
                    #IMPLIED    -- Default: GI of element is treated as 
                                            occurrence role name. -- 
                    type        -- Occurrence role type -- 
                                -- Reference to the topic that names 
                                   and/or otherwise characterizes the 
                                   occurrence role. The characteristics 
                                   of the referenced topic, if 
                                   appropriate, will be displayed to the 
                                   user instead of the value of the occrl 
                                   attribute. -- 
                    CDATA       -- Reference -- 
                                -- Reftype: topic -- 
                    #IMPLIED    -- Default: No topic characterizes the 
                                            occurrence role, unless this element is 
                                            an occurrence (with an occurrence role 
                                            whose meaning is instance) of a topic 
                                            whose subject is the nature of the 
                                            occurrence role. The value of the 
                                            occrl attribute will be displayed as 
                                            the occurrence role name. -- 
-- HyTime attributes controlling how embedded locations are to be processed --
                    HyTime      -- HyTime architectural form name -- 
                    NAME 
                    #FIXED 
                    anchspec 
                    linktrav    -- Hyperlink traversal rules -- 
                                -- Traversal between anchors of hyperlinks: 
                                     A any traversal or departure (EID) 
                                     D departure after internal arrival 
                                     E traversal after external arrival 
                                     I traversal after internal arrival 
                                     N no traversal after internal arrival 
                                     P no internal arrival 
                                     R return traversal after internal arrival -- 
                    NAMES       -- Lextype: ("A"|"EI"|"ER"|"ED"|"EN"|"EP"|"ERD"| 
                                             "I"|"ID"|"D"|"N"|"P"|"R"|"RD")     -- 
                    A 
                    listtrav    -- List traversal rules -- 
                                -- Traversal between members of list anchors: 
                                     A adjacent (both left and right) traversal 
                                     L left traversal 
                                     N no traversal 
                                     R right traversal 
                                     W wrapping traversal -- 
                    NAMES       -- Lextype: ("A"|"AW"|"L"|"LW"|"N"|"R"|"RW")  -- 
                    N           -- Default: Show the whole list -- 
                    multmem 
                    (single|list|corlist) 
                    list 
                    emptyanc 
                    (error|noterror) 
                    error 
                    HyNames 
                    CDATA 
                    "anchrole occrl" >

The attributes have the following significance:

scope

The optional scope attribute can be used to identify the set of topics that indicate the contexts in which this occurrence is valid. These topics are added to those defined as the scope of the containing topic conformant elements, including the added themes defined by the addthems attribute of the containing topicmap conformant element or any assigned using an addthms element that references occurs conformant elements within this document. During deserialization each scoping topic is related to this Occurrence item through a scope connection.

occrl

The optional occrl attribute can be used to identify the role the occurrence plays. If no value is specified the generic identifier of the occurs conformant element is deemed to identify the role played by the occurrence. This attribute is ignored during deserialization.

type

The optional type attribute can be used to identify the single topic whose names can be used to display information about the occurrence role type. During deserialization the identified Topic item is connected to the Occurrence item through a occurrenceType connection.

If the type attribute is specified, and if the topic referenced by the type attribute has a name characteristic (base name or display name) that lies within the scope that is appropriate to the topic map user's context, the referenced topic name characteristic is used to characterize the association type for the user. Otherwise the value of the occrl attribute (or, if the occrl attribute is not specified, the generic identifier) is used to characterize the association.

Note: The topic referenced by the type attribute can have many names in scopes designed for many different user contexts, including many different natural languages and delivery platforms, while the occrl attribute or generic identifier is just a single token. Therefore, use of a topic, referenced by the type attribute, to characterize the association type offers far more flexibility and representational power than the simple mnemonic naming facility offered by the occrl attribute or generic identifier.

The other attributes associated with the occurs architectural form are used by HyTime engines to manage the way links between lists of anchor specifications (anchspec) can be traversed. No restrictions are placed on the use of these anchor specifications by default, the occrl attribute being mapped to the HyTime anchrole attribute. These attributes, which will normally be assigned fixed values in the DTD of a specific application, are ignored during deserialization.

Issue (HyTM-aoccrl):

Should occrl be treated as an association of the type used for linktype attribute values?

2.6 The assoc architectural form

The HyTM assoc architectural form is used to express associations (relationships) between topics. The assocrl child elements provide the association role players of the association.

During deserialization each assocc conformant element generates a SAM Association information item.

The assoc architectural form is declared as follows:

<!element assoc                 -- Association link --
                                -- ISO 13250:2002 Clause 5.3.1 --
          - O (assocrl)+ >
<!attlist assoc     scope       -- Scope --
                                -- Reference to themes that are added to
                                   the scope within which the association
                                   is applicable. --
                    CDATA       -- Reference --
                                -- Reftype: topic+ --
                    #IMPLIED    -- Default: Scope is unconstrained. --
                    linktype    -- Hyperlink type. --
                                -- Mnemonic name for the association type. --
                                -- Note: Not displayed for the topic map
                                         user if the topic referenced by the
                                         type attribute has displayable
                                         characteristics within the user's scope. --
                    NAME
                    #IMPLIED    -- Default: Generic identifier --
                    type        -- Association type --
                                -- Topic whose subject is the class of
                                   association of which this association
                                   is an instance. --
                    CDATA       -- Reference --
                                -- Reftype: topic --
                    #IMPLIED    -- Default: No type is specified by this attribute. --
                                -- Note: A type might exist by virtue of
                                         the fact that this association link is
                                         an occurrence (where the occurrence
                                         role means "instance") of a topic whose
                                         subject is the nature of the
                                         association, however. --  
-- HyTime attributes identifying how embedded elements are to be processed --
                    HyTime      -- HyTime architectural form name --
                    NAME
                    #FIXED
                    varlink   >

The attributes have the following significance:

scope

The optional scope attribute can be used to identify the set of topics that indicate the contexts in which this association is valid. These topics are added to those defined by the added themes defined by the addthems attribute of the containing topicmap conformant element or any assigned using an addthms element that references assoc conformant elements within this document. During deserialization each scoping topic is related to this Association item through a scope connection. 

linktype

The optional linktype attribute (which is a HyTime attribute required by varlink conformant linking elements) can be used to identify the type of link being made. If no value is specified the generic identifier assigned to the element defined using this architectural form is used. During deserialization a SAM Topic item is created to represent the linktype or generic identifier and an association is made between this Topic item and the Association item created by this assoc conformant element.

type

The optional type attribute can be used to identify the single topic whose names can be used to display information about the association type. During deserialization the identified a Topic item is connected to the Association item as the associationType.

If the type attribute is specified, and if the topic referenced by the type attribute has a name characteristic (base name or display name) that lies within the scope that is appropriate to the topic map user's context, the referenced topic name characteristic is used to characterize the association type for the user. Otherwise the value of the linktype attribute (or, if the linktype attribute is not specified, the generic identifier) is used to characterize the association.

Note: The topic referenced by the type attribute can have many names in scopes designed for many different user contexts, including many different natural languages and delivery platforms, while the linktype attribute or generic identifier is just a single token. Therefore, use of a topic, referenced by the type attribute, to characterize the association type offers far more flexibility and representational power than the simple mnemonic naming facility offered by the linktype attribute or generic identifier.

Issue (HyTM-assoc-linktypes):

SAM does not have a property in which the linktype/GI association can be recorded. Should topics created for linktype associations be typed through a specific PSI?

Issue (HyTM-assoc-scope):

The comment in ISO 13250 to the effect that "Scope is unconstrained" would seem to be incorrect as scope is always constrained by the added themes of the enclosing topic map according to the definitions of the addthms element and addthems attribute. 

Issue (HyTM-assoc-type):

Do we need to say anything about the class-instance relationships created by type attribute values? In particular should Note 39 of clause 5.3.1 be propagated to this specification? Should SAM make any reference to this relationship?

2.7 The assocrl architectural from

The HyTM assocrl architectural form is used to add one or more players of the same association role type to the association created by a parent element conforming to the assoc architectural form. The contents of each assocrl conformant element must one or more HyTime location addresses that locate one or more topics in a topic map (though not necessarily in the current topic map).

Note: Within a single association link, more than one assocrl conformant element may reference the same topic, in which case the topic plays multiple roles in the association. The containing assoc conformant element can, therefore, assert that a topic has one or more relationships to itself.

Note: All topics referenced in the content of a set of assocrl conformant elements within a given assoc conformant element play their roles within the same scope, which is specified as part of the definition of the assoc conformant element.

During deserialization each assocrl conformant element generates a SAM Association Role information item.

The assocrl architectural form is declared as follows:

<!element assocrl               -- Association role --
                                -- ISO 13250:2002 Clause 5.3.2 --
          - O (%loc;)+          -- Reftype: topic+ --       >
<!attlist assocrl   anchrole     -- Anchor role --
                                 -- Note: Not displayed for the topic map
                                          user if the topic referenced by the
                                          type attribute has displayable
                                          characteristics within the user's scope. --
                    NAME
                    #IMPLIED     -- Default: GI of element is treated as
                                             anchor role. --
                    type         -- Association role type --
                                 -- Reference to the topic that names
                                    and/or otherwise characterizes the
                                    association role. The characteristics
                                    of the referenced topic, if
                                    appropriate, will be displayed to the
                                    user instead of the value of the
                                    anchrole attribute. --
                    CDATA        -- Reference --
                                 -- Reftype: topic --
                    #IMPLIED     -- Default: No topic characterizes the
                                             association role, unless this element
                                             is an occurrence (with an occurrence
                                             role whose meaning is instance) of a
                                             topic whose subject is the nature of
                                             the association role. The value of the
                                             anchrole attribute will be displayed as
                                             the association role name. --
-- HyTime attributes controlling how embedded locations are to be processed --
                    HyTime      -- HyTime architectural form name -- 
                    NAME 
                    #FIXED 
                    anchspec 
                    linktrav    -- Hyperlink traversal rules -- 
                                -- Traversal between anchors of hyperlinks: 
                                     A any traversal or departure (EID) 
                                     D departure after internal arrival 
                                     E traversal after external arrival 
                                     I traversal after internal arrival 
                                     N no traversal after internal arrival 
                                     P no internal arrival 
                                     R return traversal after internal arrival -- 
                    NAMES       -- Lextype: ("A"|"EI"|"ER"|"ED"|"EN"|"EP"|"ERD"| 
                                             "I"|"ID"|"D"|"N"|"P"|"R"|"RD")     -- 
                    A 
                    listtrav    -- List traversal rules -- 
                                -- Traversal between members of list anchors: 
                                     A adjacent (both left and right) traversal 
                                     L left traversal 
                                     N no traversal 
                                     R right traversal 
                                     W wrapping traversal -- 
                    NAMES       -- Lextype: ("A"|"AW"|"L"|"LW"|"N"|"R"|"RW")  -- 
                    N           -- Default: Show the whole list -- 
                    multmem 
                    (single|list|corlist) 
                    list 
                    emptyanc 
                    (error|noterror) 
                    error                >  

The attributes have the following significance:

anchrole

The optional HyTime defined anchrole attribute can be used to provide a mnemonic for the role the association member(s) located by this assocrl plays. If no value is specified the generic identifier of the anchrole conformant element is deemed to indicate the role played by the locators. This attribute is ignored during deserialization.

type

The optional type attribute can be used to identify the single topic whose name characteristics can be used to display information about the association role type. During deserialization the identified a Topic item is connected to the AssociationRole item as the associationRoleType.

If the type attribute is specified, and if the topic referenced by the type attribute has a name characteristic (base name or display name) that lies within the scope that is appropriate to the topic map user's context, the referenced topic name characteristic is used to characterize the association type for the user. Otherwise the value of the anchrole attribute (or, if the anchrole attribute is not specified, the generic identifier) is used to characterize the association.

Note: The topic referenced by the type attribute can have many names in scopes designed for many different user contexts, including many different natural languages and delivery platforms, while the anchrole attribute or generic identifier is just a single token. Therefore, use of a topic, referenced by the type attribute, to characterize the association type offers far more flexibility and representational power than the simple mnemonic naming facility offered by the anchrole attribute or generic identifier.

The other attributes associated with the assocrl architectural form are used by HyTime engines to manage the way links between lists of anchor specifications (anchspec) can be traversed. No restrictions are placed on the use of these anchor specifications by default. These attributes, which will normally be assigned fixed values in the DTD of a specific application, are ignored during deserialization.

Issue (HyTM-assocrl-type):

The comment in ISO 13250 to the effect that "Default: No topic characterizes the association role, unless this element is an occurrence (with an occurrence role whose meaning is instance) of a topic whose subject is the nature of the association role" would seem to be incorrect. How can an association role be defined as an occurrence? The accompanying text suggesting that an occurrence of the topic could point to assocrl element to provide a link from the topic to its use introduces a problem in that the scope of the occurrence can be different for each role of the association, or for each instance of a particular role, which the model for assoc seeks to make impossible. 
NB: The wording of the comment seems to be inherited from the wording used for facets.

Do we need to say anything about the class-instance relationships created by type attribute values? In particular should Note 43 of clause 5.3.2 be propagated to this specification? Should SAM make any reference to this relationship?

Should anchrole (and occrl) be used to create SAM Topic items and associations in the same way the linktype attributes for topics and assocs do?

2.8 The addthms architectural form

The HyTM addthms architectural form is used to add a set of scoping themes to some of the scoped elements within a topic map, which may be a topic map other than the local one. This element allows topic maps to assign differentiating scopes to elements in one or more topic maps that may need to be merged with each other. Each document to have themes added must be declared as an entity within the DTD using this architectural form.

The addtms architectural form is declared as follows:

<!element addthms               -- Themes to be added -- 
                                -- (To scopes specified by topic map 
                                    documents and/or by topic links and/or 
                                    association links.) -- 
                                -- ISO 13250:2002 Clause 5.4 -- 
          - O (TMBrid)*         -- No content defined by the Topic Maps architecture -- > 
<!attlist addthms               -- Themes to be added -- 
                                -- ISO 13250:2002 Clause 5.4 -- 
                    addthems    -- Added themes -- 
                                -- Themes to be added to the scopes 
                                   specified by the tmdocs and cassign attributes --
                    CDATA       -- Reference -- 
                                -- Reftype: topic+ -- 
                    #REQUIRED 
                    tmdocs      -- Topic map document entities -- 
                    ENTITIES    -- Constraint: Must be one or 
                                               more document entities of 
                                               topic map documents. -- 
                    #IMPLIED 
                    cassign     -- Characteristic assigners -- 
                                -- Elements that assign characteristics to 
                                   topics. The themes specified by the 
                                   addthems attribute are to be added to 
                                   the scopes within which the 
                                   characteristics they specify are 
                                   regarded as valid -- 
                    CDATA       -- Reference -- 
                                -- Reftype: (topic | topname | basename | 
                                             dispname | sortname | occurs | assoc)+ 
                    -- 
                    #IMPLIED     >

The attributes have the following significance:

addthems

The compulsory addthems attribute must be used to identify the set of scoping topics that are to be assigned as themes to the identified documents. 

tmdocs

The optional tmdocs attribute can be used to identify a set of external entities that contain topicmap conforming elements to which the topics identified by the addthems attribute are to become part of the added themes set. If no value is specified the scoping topics are assigned to the local elements of the types identified by the cassigns attribute.

cassign

The optional cassign attribute identifies the types of HyTM architectural forms which are to have the scoping themes added to conformant elements.

2.9 The facet architectural form

The HyTM facet architectural form is used to assign property/value pairs to information resources including, but not restricted to, those defined within the topic map. The property being assigned is identified by facet conforming elements, which can assign multiple values to multiple locations through the embedded set of fvalue conformant elements.

During deserialization facet/value pairs are used to automatically generate referencable SAM Topic information items, while the locations assigned the values become SAM Occurrence information items for these Topic items.

The facet architectural form is declared as follows:

<!element facet                 -- Facet link --
                                -- ISO 13250:2002 Clause 5.5.1 --
          - O (fvalue)+   >
<!attlist facet     linktype    -- Hyperlink type. --
                                -- Mnemonic name for the property (facet type). --
                                -- Note: Not displayed for the topic map
                                         user if the topic referenced by the
                                         type attribute has displayable
                                         characteristics within the user's scope. --
                    NAME
                    #IMPLIED    -- Default: Generic identifier --
                    type        -- Facet type --
                                -- Topic whose subject is the property of
                                   the property/value pair(s) being
                                   assigned to the anchor(s). --
                    CDATA       -- Reference --
                                -- Reftype: topic --
                    #IMPLIED    -- Default: No facet type topic is
                                            specified by this attribute. --
                                -- Note: A facet type topic might exist by
                                         virtue of the fact that this facet link
                                         is an occurrence (where the occurrence
                                         role means "instance") of a topic whose
                                         subject is the nature of the property,
                                         however. --  
-- HyTime attribute identifying form of link --
                    HyTime      -- HyTime architectural form name --
                    NAME
                    #FIXED
                    varlink   >

The attributes have the following significance:

linktype

The optional linktype attribute (which is a HyTime attribute required by varlink conformant linking elements) can be used to identify the type of a link being made to the resource by embedded fvalue elements. If no value is specified the generic identifier assigned to the element defined using this architectural form is used. During deserialization a SAM Topic item is created to represent the linktype or generic identifier and an association is made between this Topic item and the Topic items created to represent the embedded facet values.

type

The optional type attribute can be used to identify the single topic whose names can be used to display information about the facet type. 

If the type attribute is specified, and if the topic referenced by the type attribute has a name characteristic (base name or display name) that lies within the scope that is appropriate to the topic map user's context, the referenced topic name characteristic is used to characterize the association type for the user. Otherwise the value of the linktype attribute (or, if the linktype attribute is not specified, the generic identifier) is used to characterize the association.

Note: The topic referenced by the type attribute can have many names in scopes designed for many different user contexts, including many different natural languages and delivery platforms, while the linktype attribute or generic identifier is just a single token. Therefore, use of a topic, referenced by the type attribute, to characterize the association type offers far more flexibility and representational power than the simple mnemonic naming facility offered by the linktype attribute or generic identifier.

The facet architectural form is derived from the varlink element type of the HyTime architecture.

Issue (HyTM-facet-type):

Do we need to say anything about the class-instance relationships created by type attribute values? In particular should Note 49 of clause 5.5.1 be propagated to this specification? 

2.10 The fvalue architectural form

The HyTM fvalue architectural form is used to assign user-defined values to the property identified by the containing facet conformant element. The information resources with which the property/value pair is associated are referenced through the HyTime location addresses specified as the content of the element.

The fvalue architectural form is declared as follows:

<!element fvalue                -- Facet value --
                                -- ISO 13250:2002 Clause 5.5.2 --
          - O  (%loc;)*      >
<!attlist fvalue    facetval    -- Facet value name --
                                -- Token is value of property being assigned. --
                    CDATA
                    #IMPLIED    -- Default: Facet value name is GI of element. --
                    type        -- Facet value type --
                                -- Reference to a topic whose subject is
                                   the significance of the facet value name. --
                    CDATA       -- Reference --
                                -- Reftype: topic --
                    #IMPLIED    -- Default: No facet value type topic is
                                   specified by this attribute. --
                                -- Note: A facet value type topic might
                                         exist by virtue of the fact that this
                                         fvalue element is an occurrence (where
                                         the occurrence role means "instance")
                                         of a topic whose subject is the
                                         significance of the facet value name,
                                         however. --
-- HyTime attributes controlling how embedded locations are to be processed --
                    HyTime      -- HyTime architectural form name -- 
                    NAME 
                    #FIXED 
                    anchspec 
                    linktrav    -- Hyperlink traversal rules -- 
                                -- Traversal between anchors of hyperlinks: 
                                     A any traversal or departure (EID) 
                                     D departure after internal arrival 
                                     E traversal after external arrival 
                                     I traversal after internal arrival 
                                     N no traversal after internal arrival 
                                     P no internal arrival 
                                     R return traversal after internal arrival -- 
                    NAMES       -- Lextype: ("A"|"EI"|"ER"|"ED"|"EN"|"EP"|"ERD"| 
                                             "I"|"ID"|"D"|"N"|"P"|"R"|"RD")     -- 
                    A 
                    listtrav    -- List traversal rules -- 
                                -- Traversal between members of list anchors: 
                                     A adjacent (both left and right) traversal 
                                     L left traversal 
                                     N no traversal 
                                     R right traversal 
                                     W wrapping traversal -- 
                    NAMES       -- Lextype: ("A"|"AW"|"L"|"LW"|"N"|"R"|"RW")  -- 
                    N           -- Default: Show the whole list -- 
                    multmem 
                    (single|list|corlist) 
                    list 
                    emptyanc 
                    (error|noterror) 
                    error 
                    HyNames 
                    CDATA 
                    "anchrole facetval" >
      

The attributes have the following significance:

facetval

The optional facetval attribute can be used to identify the value to be assigned to the property (facet). If no value is specified the generic identifier of the fvalue conformant element is deemed to identify the value to be assigned.

type

The optional type attribute can be used to identify the single topic whose names can be used to display information about the assigned value. 

If the type attribute is specified, and if the topic referenced by the type attribute has a name characteristic (base name or display name) that lies within the scope that is appropriate to the topic map user's context, the referenced topic name characteristic is used to characterize the association type for the user. Otherwise the value of the facetval attribute (or, if the facetval attribute is not specified, the generic identifier) is used to characterize the association.

Note: The topic referenced by the type attribute can have many names in scopes designed for many different user contexts, including many different natural languages and delivery platforms, while the facetval attribute or generic identifier is just a single token. Therefore, use of a topic, referenced by the type attribute, to characterize the association type offers far more flexibility and representational power than the simple mnemonic naming facility offered by the facetval attribute or generic identifier.

The other attributes associated with the fvalue architectural form are used by HyTime engines to manage the way links between lists of anchor specifications (anchspec) can be traversed. No restrictions are placed on the use of these anchor specifications by default, the facetval attribute being mapped to the default HyTime anchrole attribute. These attributes, which will normally be assigned fixed values in the DTD of a specific application, are ignored during deserialization.

Issue (HyTM-fvalue-type):

Do we need to say anything about the class-instance relationships created by type attribute values? Why does type not have the same relationship to facetval as applies for linktype for facet conformant elements?

3.1 Common processing rules

This section defines common processing rules used throughout this specification. These rules are referenced from the sections they apply to.

3.2 topicmap conformant elements

A HyTM topicmap conformant element causes a SAM Topic Map item to be created.

If the topicmap conformant element has an id attribute a SAM Locator item is created, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier of the topicmap conformant element, as defined in 3.1.1 Computing the location of an element. A reference to this Locator item is added to the [source locators] property of the Topic Map item.

The list of topic identifiers provided in the addthems attribute is recorded in a form that allows these topics to be used as scoping topics for all embedded architectural elements.

Each topic and assoc conformant element within the topicmap conformant element is processed to extract the specified set of information items.

3.3 topic conformant elements

A HyTM topic conformant element causes a SAM Topic item to be created and a reference to this item is inserted into the [topics] property of the Topic Map item created by the enclosing topicmap conformant element.

The id attribute causes a SAM Locator item to be created, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier of the topic conformant element, as defined in 3.1.1 Computing the location of an element. A reference to this Locator item is added to the [source locators] property of the Topic item.

The identity attribute, if it contains a value, causes a SAM Locator item to be created with the [notation] property set to "HyTM" and the [reference] property set to a UTF-8 string containing the value of the identity attribute. This Locator item is added to the [subject identifiers] property of the Topic item.

Issue (HyTM-identity):

Are there circumstances where the value of the identity attribute cannot validly converted to UTF-8?

If the types attribute contains a valid reference to one or more topics the rules defined in Clause 5.1 of [SAM] are applied to create an association between this topic and each of the topics identified within the attribute value. Each association will have its [type] property set to a reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#type-instance. One of the two association roles identified by each created association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#instance. The [role player] property of this association role must reference this Topic item. The other association role identified by each created association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#type. The [role player] property of this association role must reference the Topic item associated with one of the topics identified in the types attribute.

The list of topic identifiers provided in the scope attribute is recorded in a form that allows these topics to be added as scoping topics to all embedded architectural elements. Any additional themes that are assigned to topic conformant elements by an addthms conformant element within the same topic map, or by the addthems attribute of the containing topicmap conformant element, are added to the list provided by the scope attribute.

If the value assigned to the linktype attribute has not been used as the value of the linktype attribute for a previous topic conformant element, a SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~topic-xxx-linktype" where xxx is the value of the linktype attribute. If a value has not been assigned to the linktype attribute and the generic identifier assigned to the topic conformant element has not previously occurred as the generic identifier of a topic conformant element, a SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~topic-xxx-GI" where xxx is the unique identifier assigned to the topic conformant element being processed.

A SAM Association item is created which its [type] property set to a reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/hytm/1.0/#topic-linktype. One of the two association roles identified by each created association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/hytm/1.0/#topic. The [role player] property of this association role must reference the unique identifier of this Topic item, as specified in its id attribute. The other association role identified by each created association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/hytm/1.0/#linktype. The [role player] property of this association role must reference the Topic item that represents the value of the linktype attribute or the generic identifier of this element.

Issue (HyTM-linktype-GI):

Should we define a fixed topic or PSI that should be referenced by the [type] property for any name created during the deserialization of linktype attributes or the GI name used in the absence of such a value for this attribute? (A predefined type might simplify the separation of auto-generated topics from those defined manually.)

3.4 topname conformant elements

A HyTM topname architectural form has no direct effect on the information set, but changes the interpretation of its child elements. 

After having all the added themes assigned to topname conformant elements using an addthms element that references this topic map, the list of topic identifiers provided in the scope attribute is recorded in a form that allows these topics to be added as scoping topics to all embedded architectural elements. 

If the topname element has an id attribute that attribute is ignored.

3.5 basename conforrmant elements

A HyTM basename conformant element causes a SAM Topic Name item to be created, and reference to it to be added to the [topic name] property of the Topic item created by the parent topic element.

The parsed character data that forms the content of a basename conformant element is recorded as the [value] property of the Topic Name item.

If the basename conformant element has an id attribute a SAM Locator item is created from it, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier assigned to this basename conformant element, as defined in 3.1.1 Computing the location of an element. A reference to the Locator item is added to the [source locators] property of the Topic Name item.

The list of topic identifiers provided in the scope attribute, if present, is concatenated with the list of scoping topics assigned to the enclosing topname conformant element, and those of its parent topic conformant element, together with the added themes assigned to the enclosing topicmap conformant element. Any additional themes that are assigned to basename conformant elements by an addthms conformant element within the same topic map are added to the list. For each of the topics in the concatenated list a reference to the Topic item created to represent the referenced topic is added to the [scope] property of the Topic Name item.

3.6 dispname conformant elements

A HyTM dispname conformant element causes a SAM Variant item to be created, and reference to it to be added to the [variants] property of each of the Topic Name items created for basename conformant elements that are contained in the parent topname conformant element.

If the dispname conformant elements contains parsed character data the string is recorded as the [value] property of the Variant item. If the content of the dispname conformant element is defined within a TMBrid conformant topic map bridging element the TMBrid element and any child elements and their contents are serialized as a UTF-8 string before being recorded within the [value] property. 

Issue (HyTM-TMBrid-serialization):

Is it valid to require that the serialized string be UTF-8 conformant, or should it remain in the character set used for the HyTime source document? (Same rules should apply for the contents of location elements used to locate occurrences, etc.)

If the dispname conformant element has an id attribute a SAM Locator item is created from it, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier assigned to the dispname conformant element, as defined in 3.1.1 Computing the location of an element. A reference to this Locator item is added to the [source locators] property of the Variant item.

The list of topic identifiers provided in the scope attribute, if present, is concatenated with the list of scoping topics assigned to the enclosing topname conformant element, and those of its parent topic conformant element, together with the added themes assigned to the enclosing topicmap conformant element. Any additional themes that are assigned to dispname conformant elements by an addthms conformant element within the same topic map are added to the list. For each of the topics in the concatenated list a reference to the Topic item created to represent the referenced topic is added to the [scope] property of the Variant item.

Issue (HyTM-dispname-sortname):

How can a dispname variant be distinguished from a sortname variant? Graham Moore suggested that the Variant item be associated with a predefined SAM Topic item that has a subject identifier whose [reference] property contains http://psi/topicmaps.org/sam/1.0/#sort. The problem with this is that no such link to a Topic item is shown in Section 3.6 of the SAM. Section 5.3 of the SAM model indicates that "A variant item that has a topic with this subject indicator (http://psi/topicmaps.org/sam/1.0/#display) in its [scope] property .... " should be used. The [scope] property is supposed to contain "a reference to the Topic item created to represent the referenced topic". The suggested PSI does not conform to these rules, so we must create a predefined Topic item that can be referenced. This link needs to be recorded in Section 3.6 of the SAM. An alternative approach might be to use a [type] property, of the type assigned to the Base Name item but not used for that item. 

3.7 sortname conformant elements

A HyTM sortname conformant element causes a SAM Variant item to be created, and reference to it to be added to the [variants] property of each of the Topic Name items created for basename conformant elements that are contained in the parent topname conformant element. The Variant item is associated with a predefined SAM Topic item that has a subject identifier whose [reference] property contains http://psi/topicmaps.org/sam/1.0/#sort.

The parsed character data becomes the [value] property of the Variant item.

If the sortname conformant element has an id attribute a SAM Locator item is created from it, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier of the sortname conformant element, as defined in 3.1.1 Computing the location of an element. A reference to the Locator item is added to the [source locators] property of the Variant item.

The list of topic identifiers provided in the scope attribute, if present, is concatenated with the list of scoping topics assigned to the enclosing topname conformant element, and those of its parent topic conformant element, together with the added themes assigned to the enclosing topicmap conformant element. Any additional themes that are assigned to sortname conformant elements by an addthms conformant element within the same topic map are added to the list. For each of the topics in the concatenated list a reference to the Topic item created to represent the referenced topic is added to the [scope] property of the Variant item.

Issue (HyTM-sortname):

How can a sortname variant be distinguished from a dispname variant? Graham Moore suggested that the Variant item be associated with a predefined SAM Topic item that has a subject identifier whose [reference] property contains http://psi/topicmaps.org/sam/1.0/#sort. The problem with this is that no such link to a Topic item is shown in Section 3.6 of the SAM. Section 5.3 of the SAM model indicates that "A variant item that has a topic with this subject indicator (http://psi/topicmaps.org/sam/1.0/#sort) in its [scope] property .... " should be used. The [scope] property is supposed to contain "a reference to the Topic item created to represent the referenced topic". The suggested PSI does not conform to these rules, so we must create a predefined Topic item that can be referenced. This link needs to be recorded in Section 3.6 of the SAM. An alternative approach might be to use a [type] property, of the type assigned to the Base Name item but not used for that item. 

3.8 occurs conformant elements

A HyTM occurs conformant element causes a SAM Occurrence item to be created, and a reference to it to be added to the [occurrences] property of the Topic item created by the parent topic conformant element.

The HyTime location specifications that form the contents of an occurs conformant element are serialized into a string of UTF-8 characters and becomes the [value] property of the Occurrence item.

Issue (HyTM-occurs-value):

What happens if there is more than one locator? Do we need to create one Occurrence item for each such locator? [Graham Moore thinks we should, but I am not so sure.] Should the string be normalized to contain only UTF-8 compliant characters or left in the original character set associated with the HyTime DTD?

If the occurs conformant element has an id attribute a SAM Locator item is created, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier assigned to the occurs element, as defined in 3.1.1 Computing the location of an element. A reference to this Locator item is added to the [source locators] property of the Occurrence item.

The list of topic identifiers provided in the scope attribute, if present, is concatenated with the list of scoping topics assigned to the parent topic conformant element, together with the added themes assigned to the enclosing topicmap conformant element. Any additional themes that are assigned to occurs conformant elements by an addthms conformant element within the same topic map are added to the list. For each of the topics in the concatenated list a reference to the Topic item created to represent the referenced topic is added to the [scope] property of the Occurrence item.

If the type attribute contains a valid reference to a topic in the current topic map a reference to the Topic item created to represent the referenced topic is added to the [type] property of the Occurrence item.

3.9 assoc conformant elements

A HyTM assoc conformant element causes a SAM Association item to be created, and a reference to it to be added to the [association] property of the Topic Map item.

If the assoc conformant element has an id attribute a Locator item is created, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier assigned to the assoc element, as defined in 3.1.1 Computing the location of an element. A reference to this Locator item is added to the [source locators] property of the Association item.

The list of topic identifiers provided in the scope attribute, if present, is concatenated with the added themes assigned to the enclosing topicmap conformant element. Any additional themes that are assigned to assoc conformant elements by an addthms conformant element within the same topic map are added to the list. For each of the topics in the concatenated list a reference to the Topic item created to represent the referenced topic is added to the [scope] property of the Association item.

If the value assigned to the linktype attribute has not been used as a linktype for a previous assoc conformant element, a SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~assoc-yyy-linktype" where yyy is the value of the linktype attribute. If a value has not been assigned to the linktype attribute and the generic identifier of the assoc conformant element has not been used for a previous assoc conformant element which had no value for its linktype attribute, a SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~assoc-yyy-GI" where yyy is the generic identifier assigned to the assoc conformant element being processed.

A SAM Association item is created which its [type] property set to a reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/hytm/1.0/#assoc-linktype. One of the two association roles identified by each created association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/hytm/1.0/#assoc. The [role player] property of this association role must reference this Association item. The other association role identified by each created association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/hytm/1.0/#linktype. The [role player] property of this association role must reference the Topic item that represents the value of the linktype attribute or the generic identifier of this element.

If the type attribute contains a valid reference to a topic in the current topic map a reference to the Topic item created to represent the referenced topic is added to the [type] property of the Association item.

3.10 assocrl conformant elements

A HyTM assocrl conformant element causes a SAM Association Role item to be created, and a reference to it to be added to the [roles] property of the parent Association item. 

For each topic identified by the embedded HyTime location addresses a reference to the Topic item created to represent the referenced topic is added to the [role playing topic] property of the Association Rule item.

If the assocrl conformant element has an id attribute a SAM Locator item is created, with the [notation] property set to "XPointer" and the [reference] property being assigned an XML Pointer that resolves to the unique identifier assigned to the assocrl conformant element, as defined in 3.1.1 Computing the location of an element. A reference to this Locator item is added to the [source locators] property of the Association Rule item.

If the type attribute contains a valid reference to a topic in the current topic map a reference to the Topic item created to represent the referenced topic is added to the [type] property of the Association Role item.

3.11 addthm conformant elements

A HyTM addthm conformant element is used to assign additional scoping properties to all elements of a specified types within a clearly identified set of topic maps. The cassign attribute lists the types of elements the themes are to be assigned to. If no value is specified all architecturally conforming elements other than those related to the facet and addthms architectural forms are assigned the listed scopes. The tmdocs attribute identifies entity declarations that reference the documents to which the themes are to be added. If no value is specified the themes are added to those of the topic map containing the definitions.

Where no value is assigned to the tmdocs attribute, or one of the entities referenced by the tmdocs attribute is the current document, the list of topic identifiers provided in the addthems attribute is recorded in a form that allows these topics to be added to the requested set of embedded architectural elements identified by the values assigned to the cassign attribute.

Issue (HyTM-addthms):

How can the SAM process themes to be added to maps other than the local one?.

3.12 facet conformant elements

Each HyTM facet conformant element requires the creation of a new SAM Topic item that can be associated with each of the values assigned to the facet by fvalue conformant elements.

If a value assigned to the linktype attribute has not been used as the linktype value for a previous facet conformant element a new SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~facet-zzz-linktype" where zzz is the value of the linktype attribute. If a value has not been assigned to the linktype attribute and the generic identifier of the facet conformant element has not been used on any previous facet conformant element that had no value for its linktype attribute, a SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~facet-zzz-GI" where zzz is the generic identifier assigned to the facet conformant element being processed.

If the type attribute contains a valid reference to a topic in the current topic map the rules defined in Clause 5.1 of [SAM] are applied to create an association between the topic created to name the facet's property type and the topic identified within the type attribute value. Each association will have its [type] property set to a reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#type-instance. One of the two association roles identified by the association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#instance. The [role player] property of this association role must reference the facet naming Topic item. The other association role identified by the association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#type. The [role player] property of this association role must reference the Topic item associated with the topic identified in the type attribute.

3.13 fvalue conformant elements

Each HyTM fvalue conformant element requires the creation of a SAM Topic item to represent the value being assigned to its parent facet. The locations to which the value is assigned become Occurrence items for that that topic.

If the valueassigned to the facetval attribute has not been used previously to define the same facet/value pairing, a new SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~facet-zzz-value-vvv" where vvv is the value of the facetval attribute and zzz is the linktype or generic identifier of the containing facet conformant element. If a value has not been assigned to the facetval attribute and the generic identifier of the fvalue conformant element has not been used without a value for the facetval attribute within the same type of facet conformant element, a SAM Topic item is created whose [topic names] property contains a reference to a newly-created Topic Name item whose [value] property is set to "~facet-zzz-value-vvv-GI" where vvv is the generic identifier assigned to the fvalue conformant element being processed and zzz is the linktype or generic identifier of the containing facet conformant element.

The HyTime location specifications that form the contents of a fvalue conformant element are serialized into a UTF-8 string of characters that becomes the [value] property of a newly-created SAM Occurrence item. A reference to this Occurrence item is placed in the [occurrences] property of the Topic item created to represent the facet/value pair.

Issue (HyTM-fvalue-location):

What happens if there is more than one locator? Do we need to create one Occurrence item for each locator? Should the string be normalized to UTF-8?

If the type attribute contains a valid reference to a topic within the current topic map the rules defined in Clause 5.1 of [SAM] are applied to create an association between the facet value/pair and the topic identified within the attribute value. Each association will have its [type] property set to a reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#type-instance. One of the two association roles identified by the association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#instance. The [role player] property of this association role must reference the Topic item representing the facet/value pair. The other association role identified by the association must have a [type] property set to reference to a Topic item whose [subject identifiers] property contains a reference to a Locator item whose notation has been set to "URI" and whose [reference] property is http://psi.topicmaps.org/sam/1.0/#type. The [role player] property of this association role must reference the Topic item associated with the topic identified in the type attribute.