This topic is under construction for the 17.3 release of LabKey Server. For current documentation of this feature, click here.

Each field in a list or dataset is associated with a set of properties that can be edited using the field property editor shown below. The set of fields composing a list or dataset can also be called a domain, and this tool is sometimes called the domain editor.

Field Properties Editor

  • Use the ,, and buttons to the left of each field to reorder or delete fields.
  • Click on the Name, Label or Type for any field to edit them.
  • Selecting a row brings up the field properties editor: the block of tabs to the right.
  • The highlight bar indicates which field is currently selected for editing.
  • A (wrench) icon on the left will indicate a row with unsaved changes.
The interface for editing field properties looks like this:

Basic Properties

Name: This is the name used to refer to the field programmatically. It must start with a character and include only characters and numbers; it may not include spaces.

Label (Optional): The name that users will see displayed for the field. It can be longer than the name and may contain spaces.

Type: Fields come in different types, each intended to hold a different kind of data. Once defined, there are only limited ways you can change it, based on the ability to convert existing data to the new type. To change a field type, you may need to delete and recreate it, reimporting any data. Field types are:

  • Text (String)
  • Multi-Line Text
  • Boolean (True/False)
  • Integer
  • Number (Double) - A decimal number.
  • Date/Time
  • Flag (String)
  • File - The File type is only available for certain types of table types, including assay designs and sample sets, see below for a complete list. When a file has been uploaded into this field, it displays a link to the file; for image files, an inline thumbnail is shown. The uploaded file is stored in the file repository, in the assaydata folder. For General Purpose assays, the File field presents special behavior for image files; for details see Linking Assays with Images and Other Files.
  • Attachment - This type is only available for lists, see below for a complete list. This type allows you to attach documents to individual records in a list. For instance, an image file could be associated with a given row of data in an attachment field, and would show an inline thumbnail. The attached file is not uploaded into the file repository, but is stored as a BLOB field the database. By default, the maximum file size is 50MB, but this can be changed in the Admin Console using the setting Maximum file size, in bytes, to allow in database BLOBs. See Site Settings.
  • User - This type points to registered users of the LabKey Server system, found in the table core.Users.
  • Subject/Participant (String) - This type is only available in a study.
  • Lookup - See below.

Field Types Available by Data Structure

The following table show which fields are available in which sort of table/data structure. Notice that Datasets do not support File or Attachment fields. For a workaround technique, see Linking Data Records with External Files.

Field TypeDatasetListSample SetAssay Design
Test (String)YesYesYesYes
Multi-Line TextYesYesYesYes
Number (Double)YesYesYesYes
FileNo (workaround)NoYesYes
AttachmentNo (workaround)YesNoNo

Inline Thumbnails for Files and Attachments

Fields of type File and Attachment are available in certain structures including lists, sample sets, and assay run results (see the table above for details). When the file or attachment is an image, such as a .png or .jpg file, the cell in the data grid will display a thumbnail of the image. Hovering reveals a larger version.

When you export a grid containing these inline images to Excel, the thumbnails remain associated with the cell itself.

Bulk Import into the File Field Type

You can bulk import data into the File field type, provided that the files/images are already uploaded to the File Repository. For example suppose you already have a set of images in the file Repository, as shown below.

You can load these images into a File field, if you refer to the images by their full server path in the File Repository. For example, the following Sample Set refers to these images by their full server path:


On import, the Sample Set grid will display the image thumbnail as below:


You can populate a field with data via lookup into another table. Click on the Type property for a field, select the Lookup option, then select a source Folder, Schema and Table from the drop-down menus in the popup. These selections identify the source location for the data values that will populate this field. For examples, see the List Tutorial and the Advanced List Demo.

A lookup appears as a foreign key (<fk>) in the XML schema generated upon export of this study. An example of the XML generated:

<fk>          <fkDbSchema>lists</fkDbSchema>          <fkTable>Reagents</fkTable>          <fkColumnName>Key</fkColumnName> </fk>

Note that lookups into lists with auto-increment keys may not export/import properly because the rowIds in this type of list may be different in every database.

Display Properties

Display properties for a field are shown on the Display tab and control how and when the field is displayed.

Description: Verbose description of the field. XML schema name: description.

URL: A template for generating hyperlinks for this field. The ${ } syntax may be used to substitute a field's value into the URL. See URL Field Property.

Shown In Display Modes: Checkboxes allow you to choose whether or not the column is displayed in the display modes: Grid, Insert, Update, Details.

Format Properties

Format: You can create custom formats for displaying values in this column. For example, you can specify Date, DateTime or Number Formats to suit your locale. You can also configure date, datetime, and number formats at the folder, project, or site level for broader consistency. See Date & Number Display Formats.

Conditional Formats: Conditional formats let you change the way the data is displayed based on the data value. For details see Conditional Formats

Validators (Field-level Validation)

Field validators ensure that all values entered for a field obey a regular expression and/or fall within a specified range. They can automate checking for reasonableness and catch a broad range of field-level data-entry errors during the upload process.

Validators are applied in the following circumstances:

 On Existing DataOn ImportOn Update
Required ValidatorYesYesYes
Regex ValidatorNoYesNo
Range ValidatorNoYesNo

Required: When required, a field cannot be empty. Defaults to "False."

Add Regex Validator: Define a regular expression that defines what strings are valid.

  • Name: Required. A name for this expression.
  • Description: Optional. A text description of the expression.
  • Regular Expression: Required. A regular expression that this field's value will be evaluated against. All regular expressions must be compatible with Java regular expressions, as implemented in the Pattern class.
  • Error message. Optional. The message that will be displayed to the user in the event that validation fails for this field.
  • Fail when pattern matches. Optional. By default, validation will fail if the field value does not match the specified regular expression. Check this box if you want validation to fail when the pattern matches the field value, which may be an easier way to express the error cases you want to catch.
Add Range Validator:
  • Name: Required. A name for this range requirement.
  • Description: Optional. A text description of the range requirement.
  • First condition: Required. A condition to this validation rule that will be tested against the value for this field.
  • Second condition: Optional. A condition to this validation rule that will be tested against the value for this field. Both the first and second conditions will be tested for this field.
  • Error message: Required. The message that will be displayed to the user in the event that validation fails for this field.
Note: Validators are not included in XML schemas exported from a study.

For information on script-based validation, which can be used to validate rows or entire tables in a programmatic way, see Transformation Scripts.

Reporting Properties

The reporting tab allows you to set attributes used in creating reports.

Measure: A field identified as a measure contains data useful for charting and other analysis. Measures are typically numeric results/observations, like weight, or CD4 count. Only those columns identified as measures will be listed as options for the y-axis of a time chart, for example.

Data Dimension: Data dimensions define logical groupings of measures. For example, 'Gender' could be a dimension for a dataset containing a 'Height' measure, since it may be desirable to study height by gender.

Recommended Variable: Define which fields in this table/query/etc. should be prioritized as 'recommended' variables when creating new charts/reports/etc for datasets containing large numbers of columns.

Default Scale Type: For numeric field types, defines whether linear or log scales will be used by default for this field.

Advanced Properties

Missing Value Indicators: A field marked with 'Missing Value Indicators', can hold special values when values are missing. Unchecked by default. When checked, the following values are permitted:

  • Q: quality control has been applied and removed the value
  • N: data will not be provided (even if it is officially required).
Default Type: Dataset schemas can automatically supply default values when a user is entering values or when imported data tables have missing values. The "Default Type" property sets how the default value for the field is determined. "Last entered" is the automatic choice for this property if you do not alter it. Note: This property is not included in XML schemas exported from a study.


  • Editable default: An editable default value will be entered for the user. The default value will be the same for every user for every upload.
  • Last entered: An editable default value will be entered for the user's first use of the form. During subsequent uploads, the user will see their last entered value.
Default Value: For either of the "Default Types," you may wish to set a default value. The use of this value varies depending on the "Default Type" you have chosen. Note: This property is not included in XML schemas exported from a study.


  • If you have chosen "Editable default," you can set the default value through the Set Values option. Each time the user sees the form, they will see this default value.
  • If you have chosen "Last entered" for the default type, the field will show the setting entered previously, but you can still set the initial value of the field through the "Default Value" option.
Import Aliases: A set of alternate field names when importing from external files, in addition to the field's name and label. Multiple aliases may be separated by spaces or commas. To specify an alias that contains spaces, use double-quotes (") around the alias.

In most places where data is imported from files (TSV, Excel, etc) LabKey Server tries to match file column headers to property names. In some cases it also looks for matching property labels. The "Import Aliases" option offers further flexibility by allowing an arbitrary number of alternate column aliases. At import time, LabKey uses these aliases to track down values.

PHI Level: Tag a field as containing some level of PHI (Protected Health Information):

When a folder is exported or when a study is published, columns can be excluded based on the PHI level set here.

  • Not PHI: (Default) Not protected. Users with access to read the dataset can see this field.
  • Limited PHI: Users with access to limited PHI can see this field.
  • Full PHI: Only users with access to see full PHI can see this field.
  • Restricted: Only users with access to restricted information can see this field.

To tag a column at a specific PHI level:

  • Navigate to the dataset/list that contains the column you want to protect.
  • Edit the dataset/list definition.
  • In the designer, select the column you wish to protect.
  • Click the Advanced tab, select the appropriate level from the PHI Level dropdown.

Exclude From Shifting: If you check this box for a date column, the value will not be shifted on export/publication when the "Shift Participant Dates" option is selected.

Max Text Length: Specify the maximum number of characters allowed in text fields. The default value is 4000 characters. For values over 4000 characters, select Max. Selecting "Max" will utilize the max number of characters allowed by the underlying database implementation, for example, 1GB for PostgreSQL. Sample Sets and assay run fields do not support the Max setting. (Key fields and fields in the table exp.objectproperty do not support the Max setting.)

Related Topics


expand all collapse all