# Configuration XML

Both attributes and attribute types (see AttributeDescriptorInterface and AttributeTypeInterface, respectively) have an attribute named configurationXML. The purpose of this string value is to store configuration data, expressed as XML, which is used to configure or constrain the attribute. This configuration XML will be available to the attribute validators, editors, and customizers.

Note that this document only describes the proposed content of the ConfigurationXML. It does not describe how this information is edited or how the metadata is populated with it.

Since any attribute may have several validators, editors, and customizers, the configuration XML can contain configuration data for all of them. Some configuration data may be shared between these components. For example, a numeric attribute, opacity, may be constrained by a numeric range of `(0.0, 1.0)`. This range would be coded with a `<NumericRange>` tag with `min="0.0"` and `max="1.0"`. This same `<NumericRange>` tag might be used by both the `NumericRangeValidator` and the `NumericRangeEditor`. The same attribute might also have additional configuration XML that `NumericRangeValidator` and `NumericRangeEditor` do not know anything about. Similarly, an attribute may be constrained by a list of values (i.e. several <Value> items) while the default value would also contain a <Value> item to match.

One possible requirement is that some applications may wish to supply different configuration data for different users, possibly keying off a user role. I have not made a proposal for how this would be coded in the ConfigurationXML.

## Configuration XML Inventory

Following is an inventory of the configuration data that is currently supported:

- `<Configuration>`
  - `<Enumeration>`
    - `<Value>`
    - `<Text>`
    - `<SelectionRange>`
    - `<DynamicValues>`
  - `<IntegerRange>`
  - `<NumericRange>`
  - `<StringLengthRange>`

  Future support may include the following:

  - `<DateRange>`
  - `<TimeRange>`
  - `<Aliases>`
    - `<Alias>`
  - `<ColumnValues>`

  ### `<Configuration>`

  This tag is used to identify the beginning of ConfigurationXML:

  >     <Configuration version="9.1.2">
  >          ...
  >          ...
  >     </Configuration>

  The version attribute is a string value that identifies the current version of the ConfigurationXML that was created. Applications that create ConfigurationXML should create this attribute using a value of "9.1.3.2" if the attribute supports dynamic value generation (obtaining values by running a query) or if the attribute supports allowing multiple values. Otherwise, a configuration value of "9.1.2" should be used.

  ### `<Enumeration>`

  Identifies an enumeration list.

  >       <Enumeration xml:lang="language">
  >          <Value name="name0">value0</Value>
  >          <Value name="name1">value1</Value>
  >          ...
  >          <Value name="namen">valuen</Value>
  >       </Enumeration>

  #### Example: Enumeration

  An enumeration is a fixed list of values from which an attribute value is chosen. Examples of enumerations include names of statistics, user roles, security authorization levels, etc.

  For example, an attribute may be the anchor position of a chart within a report; it may be one of nine values. This list would be represented with an `<Enumeration>` list that contains one or more `<Value>` tags. Each value tag provides a name and an option label in the tag body. If no body exists, the tag name serves as the label.

  >     <Configuration>
  >        <Enumeration>
  >           <Value name="East"/>
  >           <Value name="North East"/>
  >           <Value name="North"/>
  >           <Value name="North West"/>
  >           <Value name="West"/>
  >           <Value name="South West"/>
  >           <Value name="South"/>
  >           <Value name="South East"/>
  >           <Value name="Center"/>
  >        </Enumeration>
  >     </Configuration>

  Here is an example which associates text labels with the values:

  >     <Configuration>
  >        <Enumeration>
  >          <Value name="L">
  >            <Text>Low</Text>
  >          </Value>
  >          <Value name="M">
  >            <Text>Medium</Text>
  >          <Value name="H">
  >            <Text>High</Text>
  >        </Enumeration>
  >     </Configuration>

  A validator for such an enumeration (`EnumerationValidator`) would check that an attribute value v is in this set of values by comparing the `name` attribute of each Value. The text values (`"Low", "Medium", "High"`) exist for UI selectors and are not valid values.

  #### Example: Enumeration Localization

  The previous enumeration examples are not locale sensitive. A provision to allow localized values would be to use an `xml:lang` attribute.

  >     <Configuration>
  >       <Enumeration>
  >          <Value name="LOW">
  >            <Text>Low</Text>
  >            <Text xml:lang="en">Low</Text>
  >            <Text xml:lang="es">Baja</Text>
  >            <Text xml:lang="fr">Bas</Text>
  >            <Text xml:lang="de">Niedrig</Text>
  >          </Value>
  >          <Value name="MEDIUM">
  >            <Text>Medium</Text>
  >            <Text xml:lang="en">Medium</Text>
  >            <Text xml:lang="es">Media</Text>
  >            <Text xml:lang="fr">Moyen</Text>
  >            <Text xml:lang="de">Mittel</Text>
  >          </Value>
  >          <Value name="HIGH">
  >            <Text>High</Text>
  >            <Text xml:lang="en">High</Text>
  >            <Text xml:lang="es">Alta</Text>
  >            <Text xml:lang="fr">Haut</Text>
  >            <Text xml:lang="de">Hoch</Text>
  >          </Value>
  >       </Enumeration>
  >     </Configuration>

  This localization mechanism is not confined to `<Enumeration>` but to any type configuration.

  #### Enumeration Attributes

  Currently, only the isOthersAllowed attribute is supported:

  `<Enumeration isOthersAllowed="boolean">`
    If true, then the validator/editor/customizer will allow other values than those listed. The list of values then becomes just a suggestion list of default values.

  Potential attributes may include the following:

  `<Enumeration isEmptyAllowed="boolean">`
    If true, then an empty value is also allowed.
  `<Enumeration ignoreCase="boolean">`
    If true, then `EAST` and `east` are also valid, for example.
  `<Enumeration count="int">`
    provides the number of items in the enumeration list. This is a hint which can help the xml processor preallocate arrays etc.
  `<Enumeration isAbbreviationAllowed="boolean">`
    If true, then unique abbreviations are also valid. [This attribute is just a suggestion. Note that for the above enumeration, it is not at all helpful because the value `North` is a valid choice and it is a valid abbreviation.]
  <Value alias="alternative"
    Defines an alias for an enumeration. For example,

    >             <Value alias="NE" name="North East"/>

    defines `NE` as an alias for `North East`. Note, however, that this is not extensible to more than one alias per value.

  Again, these are only suggestions. I think some of them may make the configuration overly complex. However, there have been explicit requests for `isOthersAllowed` and `isEmptyAllowed`.

  ### `<Value>`

  A value within an `<Enumeration>`.

  >       <Value name="String"/>

  or

  >       <Value name="String">
  >           text
  >       </Value>

  or

  >       <Value name="String">
  >           <Text [ xml:lang="language" ]>
  >              text
  >           </Text>
  >       </Value>

  ### `<Text>`

  The text label of a `<Value>` in an `<Enumeration>`. It is used to specify "simple text" (text that is not localized) or when there is different text for different languages.

  >        <Text [ xml:lang="lanuage" ] >
  >            text
  >        </Text>

  ### `<SelectionRange>`

  SelectionRange is a tag within an `<Enumeration>`, that is used to limit the number of selections from a list of enumerated values

  >        <SelectionRange [ min="int" ] [ max="int" ]/>

  Each of the min and max attributes are optional. The following example specifies both the minimum and maximum number of selections allowed:

  >        <SelectionRange min="1"max="2"/>

  #### Interpreting the SelectionRangeTag

  The SelectionRange Tag is an optional subtag contained within Enumeration. There has been discussion lately as to how to inpret the following conditions associated with the SelectionRange tag:

- No SelectionRange tag present
- SelectionRange tag present with a maximum specified but minimum is blank or missing
- SelectionRange tag present with a minimum specified but maximum is blank or missing

  No SelectionRangeTag implies a maximum of 1 and a minimum of either 0 or 1 depending on the setting of the required attribute (0 for false, 1 for true)

  Specifying a maximum value without a minimum value (minimum is blank or missing) assumes that the minimum is 0 if the required attribute is false and that the minimum is 1 is the required attribute is true.

  Specifying a minimum without a maximum (maximum is blank or missing) assumes an unlimited number of selections.

  ### `<DynamicValues>`

  The DynamicValues tag is used to identify a query of some sort with subtags to identify the particular datasource. The query results are used to populate the property editor:

      		<DynamicValues>
      			<InformationMapQuery location="sbip://hope/BipTree/blah/blah/foo.map">
      				<DataItem id="dataItem1"/>
      			</InformationMapQuery>
      		</DynamicValues>

  ### `<IntegerRange>`

  Identifies a possibly open-ended integer range with an optional increment value

  >        <IntegerRange [ min="int" ] [ max="int" ]  [ increment="int" ]/>

  Each of the min and max attributes are optional for the type. For example, if `max` is omitted, then the upperbound of the integer range is unbounded:

  >        <IntegerRange min="1"/>

  expresses an open-ended integer range, namely i > 0.

  #### Example

  For example, consider a property type named `IntegerRange` which validates that the property value is within an integer range. This range can be expressed with two integer values:

  >     <Configuration>
  >        <IntegerRange min="1" max="200"/>
  >     </Configuration>

  Thus, a validator for this type, of type `IntegerRangeValidator`, would use this XML, if it exists, and validate that a property value is in the integer range `1 <= i <= 200`. An editor (i.e. `IntegerRangeEditor`) could use this configuration by displaying a constrained slider instead of a simple text input field. The increment value could be used by editors that support incrementing.

  ### `<NumericRange>`

  Identifies a numeric range. Each endpoint is optional and can be specified as inclusive or exclusive.

  >        <NumericRange [ min="number" | minExclusive="number" ]
  >                      [ max="number" | maxExclusive="number" ]
  >     		 [classtype="string"] />

  `

  min

  ` and `max` are inclusive endpoints.

  classtype identities the Number subclass (Float, Double, etc.). It is used by utilities that parse the XML. It should not be specified as an input; it is derived from the min/max values.

  #### Example

  >        <NumericRange min="0.0" maxExclusive="1.0" />

  represents the numeric range [0.0, 1.0), i.e. all n where 0.0 <= n and n < 1.0

  ### `<StringLengthRange>`

  StringLengthRange is a possibly open-ended integer range used to limit the size of a string:

  >        <StringLengthRange [ min="int" ] [ max="int" ]/>

  Each of the min and max attributes are optional. The following example specifies both the minimum and maximum size of a string:

  >        <StringLengthRange min="1"max="100"/>

  ### `<DateRange (Not Currently Supported)>`

  Identifies a date range. Each endpoint is optional and is represented in ISO ISO8601 format.

  >        <DateRange [ min="yyyy-MM-dd" ] [ max="yyyy-MM-dd" ]/>

  #### Example

  >        <DateRange [ min="1970-01-01" ] [ max="2000-07-28" ]/>

  ### `<TimeRange (Not Currently Supported)>`

  Identifies a time range. Each endpoint is optional and is represented in ISO ISO8601 format.

  >        <TimeRange [ min="hh:mm" ] [ max="hh:mm" ]/>

  #### Example

  >        <TimeRange [ min="09:00" ] [ max="17:00" ]/>

  Do we also need a `<DateTimeRange>` ? Note that a date/time value could be constrained by the existence of both a `<DateRange>` and a `<TimeRange>` in the ConfigurationXML, but this has problems (what if the `<TimeRange min="">` exists, but `<DateRange min="">` does not?)

  ### `<Aliases (Not Currently Supported)>`

  Nancy Wills would like to be able to define aliases for different libname properties/options. For example, a libname may require a `PASSWORD` attribute; it may have an alias of `PWD`. Some attributes may have more than one alias. It was suggested that these aliases be coded in the ConfigurationXML for the property.

  >       <Aliases>
  >          <Alias>alias0</Alias>
  >          <Alias>alias1</Alias>
  >          ...
  >          <Alias>aliasn</Alias>
  >       </Aliases>

  ### `<Alias (Not Currently Supported)>`

  One of several aliases within an `<Aliases>` tag.

  >         <Alias>alias</Alias>

  ### `<ColumnValues>`

  This configuration represents a dynamic list of values from a column in a data table. The column is identified by a column name in the result of a query or other transformation which produces a relational table.

      <Configuration>
        <ColumnValues>
           <Column>column name</Column>
           <Table>table specification</Table>
        </ColumnValues>
      </Configuration>

  The details of how a table is specified are yet to be worked out... This needs to include sorting (locale sensitive?), whether unique values are removed, perhaps if the column data can be cached or if it should be requeried on each access or at regular intervals, etc.

  Last Modified: Fri Dec 06 2002