This is an archive copy of the IUCr web site dating from 2008. For current content please visit https://www.iucr.org.

mmCIF Dictionary Extension Templates

This document provides a number of templates which may be useful for constructing extensions to the mmCIF dictionary. The template definitions contain the items of information that should be specified when drafting a new definition. Issues related to the construction new dictionary definitions are discussed in detail in the tutorial chapter on dictionary mechanics developed for the Rutgers mmCIF Software Developers Workshop. Only the definition templates are presented here.

In order of increasing complexity, common types of dictionary extensions can be classified as:

addition of a data item which adds a new property to an existing category.
addition of a new category with no data items in common with any existing category.
addition of a new category with some data items in common with an existing category.

The following sections provide templates for each type of dictionary extension.

Adding a new data item to an existing category

In the template definition below replace the existing_category and new_item_name with the appropriate category and item names, and replace the question mark placeholders with the desired values. The new item name should include a distinguishing prefix for your local organization. Requests for local prefixes should be directed to Brian McMahon at the IUCr (bm@iucr.org).

For a data item with continuous values:

(download template)

save__existing_category.new_item_name
    _item_description.description
;              Description goes here ... 
;
    _item.name                  '_existing_category.new_item_name'
    _item.category_id             existing_category
    _item.mandatory_code          no
    _item_type.code               ?
#
#    Examples are not mandatory but are highly desirable.
#
     loop_
    _item_examples.case
    _item_examples.detail        
     ?  ?
#
#    The following items may be relevant for some definitions.
# 
    _item_default.value           ?

     loop_
    _item_range.maximum              
    _item_range.minimum           ?   ?


    _item_units.code              ?
#
#    Less common items which define relationships and dependencies
#    on other data items.
#
     loop_
    _item_dependent.dependent_name  ?

     loop_
    _item_related.related_name      
    _item_related.function_code  ?  ?

     loop_
    _item_aliases.alias_name
    _item_aliases.dictionary
    _item_aliases.version        ?   ?   ?

     save_

For a data item with discrete values:

(download template)

save__existing_category.new_item_name
    _item_description.description
;              Description goes here ... 
;
    _item.name                  '_existing_category.new_item_name'
    _item.category_id             existing_category
    _item.mandatory_code          no
    _item_type.code               ?
#
#    Examples are not mandatory but are highly desirable.
#
     loop_
    _item_examples.case
    _item_examples.detail         ?  ?
#
#    The following items may be relevant for some definitions.
# 
    _item_default.value           ?
     loop_
    _item_enumeration.value
    _item_enumeration.detail      ?  ?

     save_

Adding a new category with no common items

In this template category definition, replace NEW_CATEGORY and key_item_1 with the appropriate category name and key item(s), and replace the question mark placeholders with the desired values. The new category name should include a distinguishing prefix for your local organization. (download template)

save_NEW_CATEGORY
    _category.description
;              Description goes here ... 
;
    _category.id                  new_category
    _category.mandatory_code      no
     loop_
    _category_key.name          '_new_category.key_item_1'

     loop_
    _category_group.id           'inclusive_group'
                                 ?
     loop_
    _category_examples.detail    
    _category_examples.case      ?   ? 

     save_

Adding a new category with some common data items

This template includes a category definition and a shared item definition. In the category definition, replace NEW_CATEGORY and key_item_1 with the appropriate category name and key item(s). The shared item(s) may be listed as part of the category key if this is appropriate. The data item(s) which are shared between categories are identified as _new_category.shared_item_name in the item definition template. This name of the item and the name of the parent data item must be specified for each shared item. The question mark placeholders should be replaced with the desired values. (download template)

save_NEW_CATEGORY
    _category.description
;              Description goes here ... 
;
    _category.id                  new_category
    _category.mandatory_code      no
     loop_
    _category_key.name          '_new_category.key_item_1'

     loop_
    _category_group.id           'inclusive_group'
                                 ?
     loop_
    _category_examples.detail    
    _category_examples.case      ?   ? 

     save_

save__new_category.shared_item_name
    _item_description.description
;              This data item is a pointer to item 
               _parent_category.shared_item_name in 
               the PARENT_CATEGORY category.
;
    _item.name                  '_new_category.shared_item_name'
    _item.category_id             new_category
    _item.mandatory_code          ?
    _item_linked.parent_name    '_parent_category.shared_item_name'
    _item_linked.child_name     '_new_category.shared_item_name'
     save_

|mmCIF| Background| Dictionaries| Examples| DDL| Software| Resources| References|

Webmaster: ndbadmin@ndbserver.rutgers.edu