#########################################################################################
## I try to organize some of my thoughts about TMCL Lite in this note.
##
##
##
## Link: TMCL Lite schema example (Python style)
##
## 2004-02-28
##Copyright @ 2004 Dmitry Bogachev
##
#########################################################################################


Firstly, I define what topic map schema (Lite) includes:

- set of type topics
- set of associations supertype-subtype (can have scope)
- each supertype-subtype association has a boolean tag: allow inheritance with default value "true"
- each type topic can have a set of Partial Type Descriptions (PTD) attached to the topic
- each PTD is a set of constraints in a predefined format
- each PTD represents "necessary" rules:
    if $X isInstanceOf  $T then /set of constraints in predefined format/  
    Note: that's not a real syntax.

- Only following constraints are allowed:

      BaseNameSchema(type,scope): 
          cardMin                #Integer
          cardMax                #Integer
          dataType               #xsd and custom xml schemas
          oneOf                  # String*
          match                  #  Regular Expression*

      InternalOccurrenceSchema(type,scope): 
          cardMin
          cardMax
          dataType
          oneOf                     
          match   

      ExternalOccurrenceSchema(type,scope): 
          cardMin
          cardMax
          oneOf                     
          match

      PlayRoleSchema:(role,association,scope):    # $X can play /role/ in /association/ with /scope/
          cardMin
          cardMax
          otherPlayers              # RoleSchema*

      RoleSchema(role):
          cardMin
          cardMax
          playerType               # Topic*  list of  Types connected by 'AND'
          oneOf                    #  Topic*  list of  instance topics

   Object type PTD is defined as:

       TopicTypeDescription(topic_id):
           names                          # BaseNameSchema*
           internalOccurrences            # InternalOccurrenceSchema*
           externalOccurrences            # ExternalOccurrenceSchema*
           playRoles                      # PlayRoleSchema*

   Association type PTD is defined as:

        AssociationTypeDescription(topic_id):
           roles                          # RoleSchema*


Secondly, I define some operations on topic map schemas:

-  topic map schema can be merged:
    - set of type topics is merged
    - set of super/subtype associations is merged
    - set of PTDs for each type is merged (PTDs stay as they are)

-  it is possible to specify exceptions (set of type topics) in merging statement 
    (PTDs from excluded types are not copied to target schema)
 
-  topic map schema support following requests:
      
      getTopicTypeSchema(type_topic_ids, scope):            # String+, Scope -> TopicTypeSchema

      getAssociationTypeSchema(type_topic_id, scope):       # String,+, Scope  -> AssociationTypeSchema

      TopicTypeSchema and AssociationTypeSchema are defined as:

      TopicTypeSchema(topic_ids, scope):
         names                       # BaseNameSchema*
         internalOccurrences         # InternalOccurrenceSchema*
         externalOccurrences         # ExternalOccurrenceSchema*
         playRoles                   # PlayRoleSchema*
         conflicts                   # Conflict*

      AssociationTypeSchema(topic_id,scope):
         roles                      # RoleSchema*
         conflicts                  # Conflict*    

 - getTopicTypeSchema implements following logic:
        - collect all available PTDs for set of types in type_topic_ids.
        - create ONE TopicTypeSchema by combining all PTDs        
        - check results against predefined set of conflicts:
             cardMin<=cardMax
             oneOf != ()
             **** playerType !=Nothing (maybe  later, depends on availability of type disjoint info)
        - if there is a conflict then create a Conflict object and attach it to TopicTypeSchema
    
        -  when getTopicTypeSchema procedure tries to collect all available PTDs it relies on
           following PTD "sources"
            - explicit PTDs attached to type
            - implicit PTDs which can be inherited from supertypes
            - implicit PTDs which can be transferred from related association types
         
         -  when getTopicTypeSchema tries to collect PTDs from super types it recursively calls
            itself to produce schema for supertypes
         -  when getTopicTypeSchema tries to collect PTDs from associations it calls 
            getAssociationTypeSchema to produce schema for associations
         -  if  tag "allow inheritance" is "false" getTopicTypeSchema  does not inherit schema from syper type
         -  explicitly defined PTDs overwrite implicit (inferred) PTDs 
         -  TopicTypeSchema calculated for a type can be cached. 
         -  TopicTypeSchema can depend on scope because super/sub type associations can depend on scope
         -  getTopicTypeSchema can identify super/sub type "loops" and creates a conflict record for each 
            type schema in loop with the same loop "id". ???
            (I do not like loops in schemas...but I can have different loop resolution policy here 
            to comply with RDF/OWL)

  - getAssociationTypeSchema implements basically the same logic.

"Debugging" Schemas:

  - users "debug" schemas by asking to construct type-topic and association schemas
  - when users develop schemas they prepare set of tests: factual topic maps.
  - users "debug" schemas against tests by asking to construct topic schemas for each  topic-instance.
  - users can check set of produced conflicts
  - each conflict has some explanation which helps to trace problem
  - based on identified conflicts users can modify schemas by prohibiting inheritance and/or by defining 
    explicit PTDs which overwrite conflicts.