Hosted by CU logo University of Colorado
Powered by ESGF-CoG logo
Welcome, Guest. | Login | Create Account
ES-DOC-Models logo
You are at the CoG-CU node

CV Creation and Mindmap Rules

Controlled Vocabularies (CVs) represent the Scientific Properties of a Model Component. CVs are created in Mind Map, a specialized type of diagram, format. This format was chosen during CMIP5 to assist scientists in visually conceptualizing information. There are various software packages available to assist in their creation. CIM2.X will no longer use this format since Scientific Properties will become part of the CIM itself.

General Rules

  • The mindmaps should be named <name>_bdl.xml where <name> is a unique identifier.
  • Nodes should be to the right. Anything to the left will be ignored.
  • Component names should not end in Scheme.
  • If a component describes a parametrization/numerical scheme then it must have a SchemeType parameter.
    • SchemeName is not mandatory as some schemes have no usual name and are only identified by their type.
    • This rule can not be checked.
  • Names may only contain alphabetic characters, numeric characters, hyphen, underscore or dot.
  • Use Camel Case.
  • Specifying work in progress
    • A node and its children will be ignored if it includes the yellow triangular warning icon (messagebox_warning). This icon is meant to be used when the node is not yet complete.
    • A node and its children will be ignored if its text is in an italic font. Eg. enumerations of controlled vocabularies that have not yet been agreed.
  • "_" and "." have a special meanings:
    • Only one "_" or "." can appear in a name.
    • If oth a "_" and a "." appear, then the "_" must occur before the "." in the name.
    • "_" means "ignore everything before" when translating for ESGF
    • "." means "ignore everything after" when translating for ESGF
    • Both "_" and "." are stripped out of the name for the questionnaire.
  • Nodes are color coordinated: 
Feature Color
component Bold, not Purple (#990099)
parameter bundle Purple (#990099)
parameter bundle to be treated as a non-editable component by the questionnaire Bold and Purple (#990099)
constraint Blue (#0033ff)
parameter Brown (#996600)
value node style fork


Hierarchy rules

  • A component contains
    • [0..n] components
    • [0..n] parameter bundles
    • at least one component or parameter bundle
  • A parameter bundle contains
    • [0..n] parameters
    • [0..n] constraints
    • at least one parameter or constraint
  • A constraint contains
    • [1..n] parameters
  • A parameter contains
    • [1..n] values
  • Values are atomic

Specifying values

Different types of values are indicated by adding the following icons to a value node

  • Keyboard input (numerical value) is indicated by the Purple-1 icon
  • Keyboard input (string value) is indicated by the pencil icon
  • A coupled parameter is indicated by the Back arrow
  • Controlled vocabulary definition is the default when no icons are found

Formatting for keyboard input values

  • A keyboard input value may optionally include units.
  • These will be specified in the text of the value node.

Specifying the multiplicity of controlled vocabulary parameters

  • If a parameter has more than one potential controlled vocabulary value associated with it then the mindmaps define whether it is valid to select more than one value for the parameter, or whether only one value may be specified.
  • The following icons, which are added to the controlled vocabulary values nodes, indicate the number of allowed parameter values:
    • OR, the tick icon (button_ok)
    • XOR, the cross icon (button_cancel)
  • A consequence of this rule is that a value node and all its siblings will have the same icon.
  • Note, the AND, the yellow star icon (bookmark) has been deprecated and will now produce an error in the checker if used.

Parameter Groups

  • A parameter which contains a keyboard input value must only contain that input value. i.e. a keyboard input may not have multiple values in the mindmaps.
  • Parameters which do not naturally fit into a parameter group will be placed in a default parameter group which has the name "<component name>Attributes".
  • This default parameter group will not appear in the CIM output, or definitions hierarchy.


  • Definitions for controlled vocabulary terms are stored in the bundled mindmaps.
  • Definitions are stored as a note (pen and book icon) on the appropriate node.
  • For historical reasons (and for potential future expansion) the following format is used for notes:
    • [definition]definition text[/definition]


  • While the mindmaps for CMIP5 included constraints, none of the follow on tools could handle them because they were not exported in a machine readable way.
  • Contraints may not be part of CIM2.x
  • If the constraint in a constraint node is going to be validated by the questionnaire then it needs to conform to a certain syntax. The syntax is:
    • if paramname is [not] "value1" [or "value2"]*
      • for a parameter which contains a single value (XOR)
    • if paramname has [not] value1" [or "value2"]*
      • for a parameter which may contain multiple values (OR)
    • In both cases the "not" is optional and acts to negate the expression.
  • Constraints that do not conform to the above format are allowed but will not be validated.
Last Update: Nov. 12, 2015, 10:17 a.m. by Sylvia Murphy
Read News
Questionnaire v0.15.0.0 Released
This release implemented a RESTful framework for the Customizer. Learn more at: https://earthsyst...
ES-DOC v0.9.3 Released
This release added several new commands to the es-doc shell. Learn more at:
Questionnaire v0.14.0.0 Released
This releases changes how CIM elements are entered. Learn more at: https://earthsyst...
ES-DOC v0.9.2 Released
This version includes support for additional CIM Standard Properties. Learn more at:
Questionnaire v0.13.1.0 Released
This release prevents publication of incomplete documents. Learn more at: https://earthsyst...
Browse Projects
Start typing, or use the 'Delete' key to show all available tags.
ES-DOC-Models Tags: Cyberinstrastructure, Metadata