Field Formatting and Auto-Numbering

Documentation Configuration & Installation
,
1

Specify offers a highly flexible formatting and auto-numbering capability, allowing you to enforce structured, institution-specific formats for fields such as Catalog Number, Loan Number, and Accession Number. These field formats ensure data consistency, support automated value generation, and enable compliance with institutional or disciplinary standards.

For example, a Catalog Number may contain a few static characters representing the discipline, a separator, then the current year followed by an auto-incrementing value.

Catalog Number Example
Catalog Number Example1116×464 51.3 KB

The example above would not require the user to enter any part of the number during data entry, as each of the segment definitions are automatically added. The year and number can be edited when entering legacy data. Within the definition of the format a segment can also be defined as ‘alpha’, ‘alpha-numeric’, or ‘numeric’, which do require the user to enter the appropriate text or number. These definitions can be combined as required.

Overview

  • Format Templates: Field formats are defined as templates broken into segments (e.g., static text, year, incrementing number).
  • Auto-Numbering: Segments can be configured to auto-increment, ensuring unique values.
  • User Guidance: During data entry, the format provides a visual cue, reducing errors and enforcing uniform structure.
  • Customization: Formats can be customized for any field that requires structured identifiers.

Segment Types

Type Description Incrementable?
Numeric Only “0” through “9” numbers may be entered. Yes
Alpha Only alphabetic characters (“A”-“Z”, “a”-“z”, case-sensitive). No
Alpha-Numeric “0”–“9” plus alphabetic characters. No
Any Character Numbers, alphabetic, and/or special characters. No
Year A 4-digit numeric year value. Can be set to default to the current year. No
Separator One or more static separator characters such as -, /, ., etc. (The ‘#’ character is not allowed as a separator.) No
Constant Any unchanging value, alpha, numeric, or special characters. No
Regex A regular expression that validates the input for this segment. Useful for advanced or institution-specific validation requirements. You can learn more about configuring a regular expression here. No

How Does it Work?

UIFormatters App Resource
UIFormatters App Resource1920×1062 187 KB

A format is created by defining each segment in the Field Formatters (UIFormatters) app resource. Each field format is represented as a <field> XML element with specific attributes:

<field type="year" size="4" value="YEAR" byyear="true"/>
<field type="separator" size="1" value="-"/>
<field type="alphanumeric" size="2" value="AA"/>
<field type="numeric" size="3" inc="true"/>
  • type: The segment type (see table above).
  • size: The length/number of characters for the segment.
  • value: Default/sample value (for display and validation).
  • byyear: For year segments, whether to default to the current year.
  • inc: For numeric segments, whether to auto-increment.

When specifying the various different parts of the format a sample is shown so the user has a visual cue as to the type of value that is needed.

The image below shows an examples of a format that is used within an Accession Number on an Accession form. The Accession Number must have a 4 digit number (that represents the current year) then a two alphabet-only string followed by the number portion that is unique for all Accession Numbers.

Accession Number Format
Accession Number Format710×202 10.3 KB

Users can hover over the field to see the required format if necessary:

image
image730×188 13.3 KB

In the example above the ‘###’ portion of the Accession Number indicates that it is set to automatically increment. If it were not, the field template would appear as: ‘2025-AA-NNN’.

Example: Accession Number Format

This format enforces the following structure:

  • 4-digit year (defaults to current year)
  • Separator (-)
  • 2-letter alpha segment (user-entered)
  • Separator (-)
  • 3-digit auto-incrementing number
<format system="true" name="AccessionNumber" class="edu.ku.brc.specify.datamodel.Accession" fieldname="accessionNumber" default="true">
  <autonumber>edu.ku.brc.specify.dbsupport.AccessionAutoNumberAlphaNum</autonumber>
  <field type="year" size="4" value="YEAR" byyear="true"/>
  <field type="separator" size="1" value="-"/>
  <field type="alphanumeric" size="2" value="AA"/>
  <field type="separator" size="1" value="-"/>
  <field type="numeric" size="3" inc="true"/>
</format>

Resulting values: 2025-AB-001, 2025-XY-002, etc.

Default Field Formats and Their Purposes

Default Field Formats in Specify

The default field formats in Specify are defined in the default Field Formatters (UIFormatters) app resource and are crucial for ensuring consistent, valid, and unique identifiers across core tables such as Accession Number, Catalog Number, Loan Number, and others. Each format is associated with a specific table (via the class attribute, e.g., edu.ku.brc.specify.datamodel.Accession) and a specific field within that table (using the fieldname attribute, e.g., accessionNumber). This explicit linkage ensures that each format is only applied to the appropriate field in the correct table.

Collection Object

CatalogNumberNumeric

  • Table/Class: edu.ku.brc.specify.datamodel.CollectionObject

  • Field: catalogNumber

  • Description:
    The CatalogNumberNumeric format is a special configuration for the catalogNumber field in the CollectionObject table that enforces numeric-only catalog numbers. It uses a 9-digit format by default, and Specify automatically adds leading zeros when searching or creating records—so entering 123 will be treated as 000000123. This makes searching and data entry user-friendly and ensures numeric sorting.

    However, if you configure the format to use more or fewer than 9 digits, this auto zero-padding does not occur: users must enter the complete, correctly padded number both for searching and new entries (e.g., searching for 123 will not match 0000000123 in a 10-digit scheme). The format still enforces numeric input and auto-incrementing as configured, but the convenience of auto-padding is exclusive to the 9-digit version.

CatalogNumber

  • Table/Class: edu.ku.brc.specify.datamodel.CollectionObject
  • Field: catalogNumber
  • Description: Standard format for specimen catalog numbers. Combines the current year, a separator, and a 6-digit auto-incrementing number.
  • Example: 2025-000001
  • Auto-numbering: Yes, on the numeric segment.

CatalogNumberAlphaNumByYear

  • Table/Class: edu.ku.brc.specify.datamodel.CollectionObject
  • Field: catalogNumber
  • Description: Like CatalogNumber, but the year is always re-evaluated per year (byyear="true"). The numeric segment auto-increments in the context of each year.
  • Example: 2025-000001, then 2026-000001 (it resets each year)

CatalogNumberString

  • Table/Class: edu.ku.brc.specify.datamodel.CollectionObject
  • Field: catalogNumber
  • Description: This allows for free-form or legacy catalog numbers with minimal validation.

Expand below to see the other default field formats for Accession, Deaccession, Loan, Gift, and more:

Other Default Formats

Accession

AccessionNumber

  • Table/Class: edu.ku.brc.specify.datamodel.Accession
  • Field: accessionNumber
  • Description: The standard format for accession numbers. This format combines the current 4-digit year, a separator (-), a 2-character alphanumeric code (user-entered, often representing a subcategory or type), another separator, and a 3-digit auto-incrementing number that ensures uniqueness.
  • Example: 2025-AB-001
  • Auto-numbering: Yes, on the final numeric segment.

AccessionStringFormatter

  • Table/Class: edu.ku.brc.specify.datamodel.Accession
  • Field: accessionNumber
  • Description: Alternate accession number format. Accepts a fixed 10-character alphanumeric string, fully user-entered. No auto-numbering or structure enforcement beyond length and character set.
  • Example: A1B2C3D4E5

AccessionNumberByYear

  • Table/Class: edu.ku.brc.specify.datamodel.Accession
  • Field: accessionNumber
  • Description: Variant accession number using a generic auto-numbering scheme. After the year and separator, it includes a 2-character alphanumeric segment and a 3-character alphanumeric segment, both user-entered.
  • Example: 2025-AB-XYZ

Deaccession

DeaccessionNumber

  • Table/Class: edu.ku.brc.specify.datamodel.Deaccession
  • Field: deaccessionNumber
  • Description: Similar structure to AccessionNumber, but the numeric portion at the end is not auto-incremented by default. Useful for legacy data or when the institution manages uniqueness externally.
  • Example: 2025-XY-002
  • Auto-numbering: No.

Loan

LoanNumber

  • Table/Class: edu.ku.brc.specify.datamodel.Loan
  • Field: loanNumber
  • Description: Standard loan number format: [YEAR]-[Incremented Number]. Ensures each loan is uniquely identified within a year.
  • Example: 2025-001

Gift

GiftNumber

  • Table/Class: edu.ku.brc.specify.datamodel.Gift
  • Field: giftNumber
  • Description: Like LoanNumber, but for gifts. Year and a 3-digit incrementing number.
  • Example: 2025-001

Information Request

InfoRequestNumber

  • Table/Class: edu.ku.brc.specify.datamodel.InfoRequest
  • Field: infoReqNumber
  • Description: For information requests, using year and incrementing number.
  • Example: 2025-001

Note:
Each format’s <format> XML element always specifies the exact data model table (class) and field (fieldname) it applies to. This ensures that formats are never ambiguously or incorrectly applied, and allows for fine-grained customizations per field and table.

CatalogNumberNumeric and external formatters:
When a format includes an <external> element, as with CatalogNumberNumeric, Specify will use custom logic to parse, validate, and format the field value.

Customizing or Adding a New Format

To create a new format, add a <format> element to your Field Formatters (UIFormatters) resource. Here are concrete examples:

Example 1: Institution Code Prefix

Suppose you want all catalog numbers to start with your institution code (e.g., KU-), followed by the current year and a 5-digit incrementing number:

<format system="true" name="CatalogNumberWithPrefix" class="edu.ku.brc.specify.datamodel.CollectionObject" fieldname="catalogNumber">
  <field type="constant" size="3" value="KU-"/>
  <field type="year" size="4" value="YEAR" byyear="true"/>
  <field type="separator" size="1" value="-"/>
  <field type="numeric" size="5" inc="true"/>
</format>

Resulting value: KU-2025-00001

Example 2: Embedded Alpha and Numeric

A loan number where the first segment is 2 alpha characters (user must enter), followed by a dash, then a 3-digit incrementing number:

<format system="true" name="LoanNumberAlphaFirst" class="edu.ku.brc.specify.datamodel.Loan" fieldname="loanNumber">
  <field type="alpha" size="2" value="AA"/>
  <field type="separator" size="1" value="-"/>
  <field type="numeric" size="3" inc="true"/>
</format>

Resulting value: AB-001, CD-002, etc.

Example 3: Regular Expression Segment

For a catalog number requiring 4 digits, optionally followed by a dash and a single uppercase letter:

<format system="false" name="CatalogNumberNumericRegex" class="edu.ku.brc.specify.datamodel.CollectionObject" fieldname="catalogNumber">
  <field type="regex" value="[0-9]{4}(-[A-Z])?" pattern="####[-A]" />
</format>

Resulting values: 1234, 1234-A, 5678-X, etc.

Example 4: Separator Variants

A format using a slash / as a separator, with an alpha and numeric section:

<format system="true" name="SpecimenID" class="edu.ku.brc.specify.datamodel.CollectionObject" fieldname="catalogNumber">
  <field type="alpha" size="2" value="AA"/>
  <field type="separator" size="1" value="/"/>
  <field type="numeric" size="4" inc="true"/>
</format>

Resulting value: AB/0001, CD/0002

Tips for Modifying Field Formatters

  • Backup your Field Formatters (UIFormatters) app resource before making changes.
  • Make sure to assign the field format using the Schema Config tool.
  • System Formats (system="true") are used by default. Use system="false" when creating custom formats.
  • Each <format> element must define:
    • name: Unique identifier for the format.
    • class: The class linked to the table/model (see existing examples, but in most cases simply add the table name after (e.g. edu.ku.brc.specify.datamodel.{TableName} like edu.ku.brc.specify.datamodel.CollectionObject).
    • fieldname: The field this format applies to (e.g. catalogNumber, barCode, text1 for the selected table).
    • Segments: One or more <field> elements specifying the format’s structure.
  • Testing: After modifying or adding a format, test entry of new values to ensure the format works as intended.
  • Defaults: If you intend to set a default value for a field that matches a particular format, that needs to be set in the XML code for the view definition. See this example for reference.

Examples

Example: Creating an Auto-Incrementing Format for text3 in Collecting Event

Suppose you want to enforce a structured, auto-incrementing identifier in the text3 field of the Collecting Event table, consisting of a simple 6-digit, zero-padded number (e.g., 000001, 000002, …).

<format system="true" name="CollectingEventText3AutoInc" class="edu.ku.brc.specify.datamodel.CollectingEvent" fieldname="text3">
  <field type="numeric" size="6" inc="true"/>
</format>

Resulting values: 000001, 000002, 000003, etc.

How to add it to the form and set it in the schema:

  1. Add the above <format> element to your Field Formatters (UIFormatters) app resource within the <formats> section.
  2. Ensure the class attribute is set to edu.ku.brc.specify.datamodel.CollectingEvent and the fieldname is text3.
  3. Save the Field Formatters (UIFormatters) app resource.
  4. Go to the Schema Config and assign the format (CollectingEventText3AutoInc) to the selected field (e.g. text3 in CollectingEvent).
  5. Log out and log back in.
  6. Test by creating a new Collecting Event: the text3 field will now be pre-populated with the next available 6-digit number, auto-incremented for each new record.

You can combine this numeric segment with other segments, such as a prefix or year, by adding additional <field> elements before the numeric segment if your institution requires a more complex identifier.