Skip to main content

Codelists

Codelist is a special feature attribute data type. In fact, codelist is a collection of a codelist items. Each codelist must have a key column and a displayable column. If a feature attribute refers a codelist, it means that the value of the feature attribute must be one of the codelist item.

In general, codelists can have more than key and displayable column. It can have as many columns as needed. A codelist in general can be referenced from many feature attributes within many feature types. Sometimes there is a requirement to display different column as a description from different feature attributes that refer the same codelist. That is why the displayable column can be defined in two places. There can be the default displayable column defined in codelist definition and furthermore each feature attribute (of the codelist reference type) can redefine the displayable column by choosing another of codelist columns as displayable.

Defining Codelist​

Example: Diameter codelist metadata definition (codelist contains two columns: Identifier and Description).

<ber:model>
   ...
  <ber:codeListArray> <!-- A Collection of Codelists -->
    <ber:codeList id="cl_105" name="Diameter" dbName="C_W_DIAMETER"
                  size="small">
      <ber:description>Diameter</ber:description>
      <ber:columnArray>
        <!-- A primary key codelist column -->
        <ber:column id="ca_10501" name="Identifier" dbName="C_W_DIAMETER"
                    nillable="false" primaryKey="true">
          <ber:description>Identifier - Primary key</ber:description>
          <ber:dataType>
            <ber:decimal precision="5" scale="0"/>
          </ber:dataType>
        </ber:column>
        <!-- A displayable column -->
        <ber:column id="ca_10502" name="Description" dbName="DESCRIPTION"
                    nillable="false" display="true">
          <ber:dataType>
            <ber:string maxLength="80"/>
          </ber:dataType>
        </ber:column>
        <ber:column id="ca_10503" name="Protection area radius" dbName="WIDTH">
          <ber:dataType>
            <ber:decimal precision="20" scale="5"/>
          </ber:dataType>
          <ber:orderBy direction="ascending" position="0"/>
        </ber:column>
      </ber:columnArray>
      <ber:formArray>
        <ber:form id="fmc_105_1" name="Diameter simple">
          <ber:fieldGroup>
            <ber:field refId="ca_10501"/>
            <ber:field refId="ca_10502"/>
          </ber:fieldGroup>
        </ber:form>
        <ber:form id="fmc_105_2" name="Diameter - edit">
          <ber:fieldGroup>
            <ber:field refId="ca_10501" label="Key" length="40"/>
            <ber:field refId="ca_10502" length="80"/>
            <ber:field refId="ca_10503" label="Radius"/>
          </ber:fieldGroup>
        </ber:form>
        <ber:assignedForms>
          <ber:assignedForm usage="default" refId="fmc_105_1"/>
        </ber:assignedForms>
      </ber:formArray>
    </ber:codeList>
  </ber:codeListArray>
  ...
</ber:model>

Attributes

  • id – Unique identifier of a codelist.

  • name – Name of a codelist.

  • dbName – The codelist database storage.

  • size – Defines whether the codelist is small or large. Small codelist is always displayed as a compact list but large codelist is always displayed in a special form.

  • hierarchical – Indicates that this codelist is a hierarchical one.

  • readOnly – Defines whether the codelist is read-only (true) or editable (false).

  • unique – If true, unique constraint is generated in database for codelist column.

Inner Elements

  • description – Contains a detailed description of the codelist.

  • checkboxed – See chapter 5.9.

  • columnArray – Definition of columns of a codelist.

  • formArray – Optional description of form; form definition is necessary for some functions, e.g. for images display in LIDS clients.

The actual codelist data (the collection of codelist items) are stored in a database. It is not defined in any metadata file.

Defining Codelist Column​

The codelist column definition is quite similar to the feature attribute definition. Each column contains following information:

Attributes

  • id – Unique identifier of a codelist column. It is unique among all project meta items.

  • name – Name of a codelist column.

  • dbName – Database column name of a codelist column.

  • nillable – Specifies if this element must be filled (false) or if it can be left empty (true).

  • primaryKey – Defines whether this column is the primary key or not. Possible values are true or false.

  • display – Defines whether this column is the default displayable column or not. Possible values are true or false.

  • outputFormat - This type defines a number format string. It contains the colon with format specifier and precision (:f2 or :F0).

  • localized - Defines whether vaues of this column can be translated into other languages. Possible values are true or false. If true, database is automatically expanded by additional columns containing the translated values for all languages defined according to chapter 2.5 Language Variants. The additional columns don’t have any other definition in metadata and don’t have their own column id

Inner Elements

  • description - Contains a detailed description of the codelist column.

  • dataType – Data type of a codelist column. Same data types can be used as for feature attribute data types. Additionally, dataType binary can be used to store file, typically an image. contentType has to be defined in case of binary dataType

Example: Codelist using outputFormat parameter.

    <ber:codeList id="cl_aaa" name="Aaa" dbName="AAA" size="small">
      <ber:description>Abc abc</ber:description>
      <ber:columnArray>
...
       <ber:column id="ca_aaa_1" name="Some number" dbName="A1 outputFormat=":F4">
          <ber:dataType>
            <ber:decimal precision="20" scale="5"/>
          </ber:dataType>
        </ber:column>
        <ber:column id="ca_aaa_2" name="Image" dbName="IMAGE">
          <ber:dataType>
            <ber:binary contentType="image/png"/>
          </ber:dataType>
        </ber:column>
      </ber:columnArray>
    </ber:codeList>
warning

The data type of a codelist column can’t be a codeListRef.

Codelist Attributes​

There is a dedicated data type called codeListRef that is used for referring codelist from a feature attribute. To be able to refer codelist, the following information is supplied:

  • Identifier of a referred codelist.

  • Identifier of a displayable column; optional in case that the default displayable column is defined in codelist definition.

The displayable column is used to display readable value rather than the value of a foreign key.

Example: In the following example there is a Diameter attribute that is defined by a codelist. The ca_10502 codelist column is used as a displayable column.

<ber:attribute id="at_5012001" name="Diameter"
               dbName="C_W_DIAMETER" nillable="false">
  <ber:dataType> <!-- Reference to codelist -->
    <ber:codeListRef refId="cl_105" displayColumn="ca_10502"/>
  </ber:dataType>
</ber:attribute>
warning

When a codelist attribute is defined as nillable, an outer join between the semantic table and the related codelist table becomes necessary. Outer joins are expensive operations and can have a substantial negative impact on database performance.

tip

To minimize performance overhead, codelist attributes should be defined as mandatory whenever possible. Assigning a reasonable default value is typically more efficient than allowing null values and forcing the use of outer joins.

Sorting Codelist Values​

There is a possibility to define ordering of codelist items. The ordering of codelist items is defined for the whole codelist. The order is always used whenever codelist items are displayed. There is no possibility to define different orders for a single codelist.

Example: In the following example there is a codelist records ordering defined. The ordering depends on two codelist columns: the description and the code.

<ber:model>
   ...
  <ber:codeListArray> <!-- A Collection of Codelists -->
    <ber:codeList id="cl_105" name="Diameter" dbName="C_W_DIAMETER"
                  size="small">
      <ber:description>Diameter</ber:description>
      <ber:columnArray>
        <!-- A primary key codelist column -->
        <ber:column id="ca_10501" name="Identifier"
                    dbName="C_W_DIAMETER"
                    nillable="false" primaryKey="true">
          <ber:description>Identifier - Primary key</ber:description>
          <ber:dataType>
            <ber:decimal precision="5" scale="0"/>
          </ber:dataType>
        </ber:column>
        <!-- A description column -->
        <ber:column id="ca_10502" name="Description"
                    dbName="DESCRIPTION"
                    nillable="false">
          <ber:dataType>
            <ber:string maxLength="80"/>
          </ber:dataType>
          <!-- Sort descending according the description -->
          <ber:orderBy direction="descending" position="1" />
        </ber:column>
        <!-- A code column -->
        <ber:column id="ca_10503" name="Code" dbName="CODE"
                    nillable="true">
          <ber:dataType>
            <ber:string maxLength="30"/>
          </ber:dataType>
          <!-- Sort ascending according the code -->
          <ber:orderBy direction="ascending" position="0" />
        </ber:column>
      </ber:columnArray>
    </ber:codeList>
  </ber:codeListArray>
  ...
</ber:model>

The codelist items of the Diameter codelist are ordered according to the Code ascending and then according Description descending.

  • orderBy – Has two mandatory attributes direction (ascending/descending) and position (determines the priority of ordering).

Hierarchical Codelists​

A hierarchical codelist is a special type of a codelist. A typical example of a hierarchical codelist is a codelist defining organizational structure or territorial division. Each unit or area has another unit or area assigned as its superior.

The hierarchical XML attribute of a codelist indicates that this codelist is a hierarchical one. In the hierarchical codelist there must be a special column that holds the information about the master record. This column must contain an XML attribute superKey set to true.

Example: Definition of hierarchical codelist type.

<ber:codeList id="cl_008"
              name="Service organization unit - hierarchical"
              dbName="C_G_SERVICE_OU" size="small"
              hierarchical="true">
  <ber:description>Service organization unit -
                   hierarchical</ber:description>
  <ber:columnArray>
    <ber:column id="ca_00801" name="Identifier"
                dbName="C_G_SERVICE_OU"
                nillable="false" primaryKey="true">
      <ber:description>Identifier - Primary key</ber:description>
      <ber:dataType>
        <ber:decimal precision="5" scale="0"/>
      </ber:dataType>
    </ber:column>
    <ber:column id="ca_00802" name="Unit ID" dbName="UNIT_ID"
         nillable="false">
      <ber:dataType>
        <ber:string maxLength="40"/>
      </ber:dataType>
    </ber:column>
    <ber:column id="ca_00803" name="Description" dbName="UNIT_NAME">
      <ber:dataType>
        <ber:string maxLength="80"/>
      </ber:dataType>
    </ber:column>
    <ber:column id="ca_00804" name="Superkey"
                dbName="SUP_C_G_SERVICE_OU"
               superKey="true">
      <ber:description>Identifier - Super key</ber:description>
      <ber:dataType>
        <ber:decimal precision="5" scale="0"/>
      </ber:dataType>
    </ber:column>
  </ber:columnArray>
</ber:codeList>

Security Codelists​

In fact, security codelists are quite similar to a standard codelists but have a special meaning in the project. The security codelist defines row level access rights to features.

The security codelist is defined in metadata by a securityCodelist XML element within the standard codeListArray collection. A security codelist must have new XML attributes secRefDbName and secRefNullValue defined. They describe the database references to the codelist.

For performance reasons the feature attributes referring security codelists are stored completely differently than the feature attributes referring normal codelists. As the references to normal codelists are always stored in the semantic container of a feature, the references to security codelists are stored in the feature container. Furthermore, every feature container must contain a database column for each security codelist defined in the project, even if none of the container's feature types has the security codelist attribute. The name of this database column is defined by the secRefDbName. As the NULL value cannot be used as a security codelist reference value in the database, the special value secRefNullValue is defined instead of the NULL. The value must have the type of the security codelist primary key and must not be used as the one of the correct security codelist primary key values.

Example: Large hierarchical security codelist defined.

<ber:securityCodeList id="cl_008"
              name="Service organization unit - hierarchical"
              dbName="C_G_SERVICE_OU" size="large" hierarchical="true"
              secRefDbName="SERVICE_ID" secRefNullValue="-1">
  <ber:description>Service organization unit – hierarchical,
                   security</ber:description>
 <ber:columnArray>
    <ber:column id="ca_00801" name="Identifier"
                dbName="C_G_SERVICE_OU"
                nillable="false" primaryKey="true">
      <ber:description>Identifier - Primary key</ber:description>
      <ber:dataType>
        <ber:decimal precision="5" scale="0"/>
      </ber:dataType>
    </ber:column>
    <ber:column id="ca_00802" name="Unit ID" dbName="UNIT_ID"
         nillable="false">
      <ber:dataType>
        <ber:string maxLength="40"/>
      </ber:dataType>
    </ber:column>
    <ber:column id="ca_00803" name="Description" dbName="UNIT_NAME">
      <ber:dataType>
        <ber:string maxLength="80"/>
      </ber:dataType>
    </ber:column>
    <ber:column id="ca_00804" name="Superkey" dbName="SUP_C_G_SERVICE_OU"
                superKey="true">
      <ber:description>Identifier - Super key</ber:description>
      <ber:dataType>
        <ber:decimal precision="5" scale="0"/>
      </ber:dataType>
    </ber:column>
  </ber:columnArray>
</ber:securityCodeList>

How to refer a security codelist

A feature type can refer the security codelist in two possible ways. The first way is a standard way: the security codelist can be referenced as a normal codelist. The second way how feature type can refer a security codelist is to define a reference by security attribute.

Example: Security attribute and a reference to a codelist.

<ber:securityAttribute id="at_5005312" name="Service ID">
  <ber:dataType>
    <ber:codeListRef refId="cl_008" displayColumn="ca_00803" />
  </ber:dataType>
</ber:securityAttribute>

The security attribute does not have the dbName. The dbName attribute is defined by a secRefDbName attribute in a security codelist definition.

Codelist Binding​

Records from two or more codelists can be bounded. That means that only some combinations of records from the codelists are allowed; they are defined in the codelist binding. A feature type can define that its codelist attribute values are bounded by a codelist binding.

The metadata definition consists of codelist binding definition and attributes binding definition.

Codelist binding definition​

Codelist binding is a container storing the allowed combinations of bounded codelists. One codelist binding can define possible combination for two or more codelists.

warning

It's not possible to define multiple references to the same codelist from one codeListBinding

tip

Ordered codelist binding is a special kind of binding which defines order of individual referred codelists. This flag influences only the client behaviour during editing the bounded attributes. The resulting state (the allowed combinations) are the same in case of ordered and not ordered definition.

Example: Definition of a codelist binding between two codelists: Material and Diameter.

  <ber:codeListArray>
    <!-- Diameter Codelist -->
    <ber:codeList id="cl_105" name="Diameter" dbName="C_W_DIAMETER" size="small">
      <ber:description>Diameter</ber:description>
      <ber:columnArray>
        <ber:column id="ca_10501" name="Identifier" dbName="C_W_DIAMETER"
                    nillable="false" primaryKey="true">
          <ber:description>Identifier - Primary key</ber:description>
          <ber:dataType>
            <ber:decimal precision="5" scale="0"/>
          </ber:dataType>
        </ber:column>
        <ber:column id="ca_10502" name="Description" dbName="DESCRIPTION">
          <ber:dataType>
            <ber:string maxLength="80"/>
          </ber:dataType>
        </ber:column>
      </ber:columnArray>
    </ber:codeList>
    <!-- Material Codelist -->
    <ber:codeList id="cl_102" name="Material" dbName="C_W_MATERIAL" size="small">
      <ber:description>Material</ber:description>
      <ber:columnArray>
        <ber:column id="ca_10201" name="Identifier" dbName="C_W_MATERIAL"
                    nillable="false" primaryKey="true">
          <ber:description>Identifier - Primary key</ber:description>
          <ber:dataType>
            <ber:decimal precision="5" scale="0"/>
          </ber:dataType>
        </ber:column>
        <ber:column id="ca_10202" name="Description" dbName="DESCRIPTION">
          <ber:dataType>
            <ber:string maxLength="80"/>
          </ber:dataType>
        </ber:column>
      </ber:columnArray>
    </ber:codeList>
  </ber:codeListArray>
  <ber:codeListBindingArray>
    <!-- Collection of codelist bindings -->
    <ber:codeListBinding id="bc_1" dbName="STD_MATERIAL_DIAMETER"
                         name="Material- Diameter Binding" ordered="false">
      <ber:description>Material – Diameter Codelist Binding</ber:description>
      <ber:boundedItemArray>
        <!-- Material codelist Reference -->
        <ber:boundedItem dbName="MATERIAL_ID">
          <ber:codeList refId="cl_102" />
        </ber:boundedItem>
        <!-- Diameter codelist Reference -->
        <ber:boundedItem dbName="DIAMETER_ID">
          <ber:codeList refId="cl_105" />
        </ber:boundedItem>
      </ber:boundedItemArray>
    </ber:codeListBinding>
  </ber:codeListBindingArray>

The codelist binding has two physical database columns MATERIAL_ID, DIAMETER_ID. These columns refer the Material and Diameter codelists. The records in this table define the possible combination of values from Material and Diameter codelists.

If there is a Material reference specified and the DIAMETER_ID column is NULL, then all records from Diameter codelist are allowed.

Attribute Binding​

If we want to use a codelist binding for a feature type, the feature type must refer all codelists in the codelist biding and must have the attribute binding definition specified.

Different attributes of different feature types can be related to the same codelists. Some feature types can define the attributes as bounded, some feature types can define the attributes linked to the same codelists as not bounded.

warning

In case of ordered codelist binding, the order of bounded attributes must be the same as the order of codelists in the codeListBinding definition.

Example: An attribute binding between the Material and Diameter attribute for the Pipeline feature type.

<ber:featureTypeArray>
  ...
  <ber:featureType
     id="ft_5012000"
     name="Pipeline" parentId="ft_5010000"
           abstract="true">
    <ber:description>Water pipeline</ber:description>
    <ber:featureAttributeArray> <!-- Array of Feature Attributes -->
     <ber:attribute id="at_5010004" name="Note" dbName="NOTE">
        <ber:description>Notes for the record</ber:description>
        <ber:dataType>  <!-- The Data Type Definition -->
          <ber:string maxLength="80"/> <!-- The string value -->
        </ber:dataType>
      </ber:attribute>
      <ber:attribute id="at_5012002" name="Length [m]"
                     dbName="LENGTH">
        <ber:description>The length of a pipeline</ber:description>
        <ber:dataType>
          <ber:decimal precision="10" scale="2"/>
          <!-- Decimal number -->
        </ber:dataType>
      </ber:attribute>
      <ber:attribute id="at_5012001" name="Diameter"
                     dbName="C_W_DIAMETER"
             nillable="false">
        <ber:dataType> <!-- Reference to a code list -->
          <ber:codeListRef refId="cl_105" displayColumn="ca_10502"/>
        </ber:dataType>
      </ber:attribute>
      <ber:attribute id="at_5012003" name="Material"
                     dbName="C_W_MATERIAL"
             nillable="false">
        <ber:dataType> <!-- Reference to a code list -->
          <ber:codeListRef refId="cl_102" displayColumn="ca_10202"/>
        </ber:dataType>
      </ber:attribute>
    </ber:featureAttributeArray>
    <!-- Array of the attribute binding array -->
    <ber:boundedAttributesArray>
      <ber:boundedAttributes>
        <!-- The Diameter – Material binding -->
        <ber:codeListBinding refId="bc_1"/>
        <!-- The Diameter attribute -->
        <ber:attribute refId="at_5012001" />
        <!-- The Material attribute -->
        <ber:attribute refId="at_5012003" />
      </ber:boundedAttributes>
    </ber:boundedAttributesArray>
  </ber:featureType>
  ...
</ber:featureTypeArray>

Filtered Codelists​

Is not defined directly, but through the reference to another object (mandatory) and through the filter over this object (optional). The filtered codelist contains id and name. It also specifies the OGC filter and refers codelist to be filtered. The filtered codelist must not refer the security or another filtered codelist.

Example: Filtered codelist.

  <ber:filteredCodeListArray>
    <ber:filteredCodeList id="cl_505" name="Diameter - Service pipe">
      <ber:description>Diameter less than 250 mm</ber:description>
      <ber:codeListFilter>
        <ber:codeList refId="cl_105"/>
        <ogc:Filter>
          <ogc:PropertyIsLessThanOrEqualTo>
            <ogc:PropertyName>ca_10501</ogc:PropertyName>
            <ogc:Literal>200</ogc:Literal>
          </ogc:PropertyIsLessThanOrEqualTo>
        </ogc:Filter>
      </ber:codeListFilter>
    </ber:filteredCodeList>
 ...
  </ber:filteredCodeListArray>

Checkboxed Codelists​

Attributes of this codelist type are represented as checkboxes. The codelist must contain exactly two values – referred by pkOn and pkOff parameters.

  • Security codelists can be defined as checkboxed as well.

  • Checkboxed codelists can be used as data types of codelists columns as well.

Example: Checkboxed codelist.

<ber:codeList id="cl_006" name="Status" dbName="C_G_STATUS" size="small">
  <ber:description>Status</ber:description>
  <ber:checkboxed pkOn="1" pkOff="2"/>
  <ber:columnArray>
    ...
  </ber:columnArray>
</ber:codeList>