Configure Result schemas

Edit existing schemas

Editing a schema is useful when you want to make minor updates without disrupting existing Result tables—such as renaming a field for clarity, adding optional fields, or reordering columns for better usability. This lets you evolve the schema over time while keeping existing data intact.

To modify an existing schema:

1. Navigate to Feature settings and select Result schemas
2. Select the schema to edit
3. Make permissible changes, such as:
   • Adding new fields (non-required)
   • Renaming fields
   • Reordering fields by dragging them into place
   • Changing a single-select field to multi-select (but not vice versa)
   • Making a required field optional

Note: Once a schema has been used to record data, certain changes (e.g., changing field types or adding required fields) are restricted. In such cases, consider creating a new version of the schema.

Archive schemas and fields

Archiving is appropriate when a schema or field is no longer in use or should be deprecated. Instead of deleting it—which could affect historical data—archiving retains the information for reporting or auditing while preventing it from being used in future entries.

Archive a Result schema

Archiving a Result schema prevents inserting new Result tables with the schema.

To archive a schema:

1. Go to Feature settings and select Result schemas
2. Hover over the schema and click the archive icon
3. Provide a reason for archiving and confirm

Archiving a Result schema does not:

• Remove any tables or data from the Warehouse
• Archive Results recorded against the schema

By default, results of archived schemas are hidden from the Results tabs of linked entities, studies, and containers, even if the results remain unarchived. To show unarchived results of archived schemas on Results tabs, contact Benchling Support.

Archive a schema field

Archiving a Result schema field does not remove any data, but limits where the field is shown.

After archiving a Result schema field, the field will no longer appear in:

• The Results tabs of linked entities, studies, and containers
• Newly inserted Result tables in Entries
• The non-$raw Warehouse table for the Result schema
• Newly completed Lab Auto runs
• API responses

After archiving a Result schema field, the field will continue to appear in:

• Existing Result tables in notebook entries and notebook templates
  • The column header for the archived field will show a purple out-of-date indicator
  • Result tables in existing notebook templates should be updated to remove the column for the archived field. To learn how to find the relevant templates, see ‘Find templates that contain your Result table’ section below
• Already completed Lab Auto runs
• The $raw Warehouse table for the Result schema

To archive a field:

1. Within the schema, hover over the field and click the archive icon
2. Provide a reason for archiving and confirm

Note: Required fields must be made optional before archiving.

When a computed (snapshot) field on a Result schema is archived, it becomes a regular field. Existing values are preserved, but new values will not be computed.
After archiving, the former computed (snapshot) field cannot be turned into a computed (snapshot) field; unarchiving the field will not revert it to being a computed (snapshot) field.

When a link field is archived, results recorded against an entity will continue to show on the entity's Results tab, even if the link field in which the entity was recorded has been archived. The archived field will, however, be hidden on the Results tab.

Add Result tables to entries and templates

After creating a Result schema, you can add its corresponding table to entries and templates. To add a Results table to an entry or template:

Insert a Result table

1. Click on Insert and select Result table from the menu
2. Use the Schema dropdown and search bar to select the Result schema
3. Click Insert

The row order on the Result schemas page corresponds to the column order in its corresponding Result table. If the order is changed or a field is archived after a table was inserted to an entry or template, the table won’t update automatically. Only newly created Result tables reflect these changes. It is possible though to re-arrange the column order or hide fields of a specific table directly in a template. Hiding fields does not change the Result schema or hide the field elsewhere in Benchling. To hide a column in a Result table, click on the column’s header and select Delete column.

With Table Mapping in structured tables in the notebook you can automate the flow of data between structured tables. This method allows you to move information from upstream structured tables into other tables, without having to copy and paste.

Find templates that contain your Result table

After updating a Result schema, you can use the Relevant templates tab on the Result schema configuration page to find templates that include:

• A Results table of the schema
• A structured table with a lookup function referencing the Result schema

Click a template link in the tab to navigate to the template and update the relevant table or lookup function.

Advanced Result configuration using JSON

Use JSON configuration when the schema UI doesn’t support a specific feature or you need finer control—such as setting display precision for decimals or configuring dropdowns with predefined lists. JSON gives you flexibility beyond the standard UI options.

For configurations not available through the UI, use the JSON editor:

1. In the schema, click Edit as JSON
2. Make desired changes and click Update 

Below you can find examples of supported changes.

Note: If the error message “fields.FIELDNAME.FIELDTYPE cannot change type on a field that contains data” displays, the field has already been used and you can no longer change the field type or add restrictions to it. 

Add minimum and maximum thresholds to number fields

If your schema field has Integer or Decimal selected as the data type, you can add minimum and maximum value thresholds.

To add thresholds in the JSON editor, add the following, replacing minimum and maximum with your numbers:

{"min":MINIMUM,
"max":MAXIMUM}

For example, add a minimum and maximum to the Viability (%) field of a Cell Viability Result table:

{ "id": "tsf_IHrUby3IzF",
"displayName": "Viability (%)",
"name": "viability",
"type": "float",
"isRequired": false,
"isMulti": false,
"isSnapshot": false,
"unitApiIdentifier": "unit_61QKnMCW",
"min": 70,
"max": 100
}

Configure decimal field placement

If your schema field has Decimal selected as the data type, you can configure the display precision. For example, a display precision of 3 would record submitted results to the thousandths position (0.000).

To specify display precision, add the following in the JSON editor, replacing number with the number of places after the decimal:

{"displayPrecision": NUMBER}

For example, add display precision 2 to the Viability (%) field of a Cell Viability Result table:

{ "id": "tsf_IHrUby3IzF",
"displayName": "Viability (%)",
"name": "viability",
"type": "float",
"isRequired": false,
"isMulti": false,
"isSnapshot": false,
"unitApiIdentifier": "unit_61QKnMCW",
"displayPrecision": 2
}

Configure text dropdown options in decimal fields

You can configure decimal (float) fields to accept text. If a user enters text values that are not configured in the field, it will be flagged as illegal to preserve data integrity. For example, a number field can be configured to accept ULOQ and LLOQ to represent the upper and lower limits of quantification, which can be useful for analytics assays.

To configure text drop-down options in a schema, first ensure the dropdown exists. You will need to input the dropdown ID in your JSON script.

To find the dropdown ID and configure your JSON script:

1. Select Dropdowns in the left-side panel, then click the dropdown.
2. Copy the end of the URL containing the dropdown ID. This begins with sfs_.
3. Replace sfs_ExampleID in the script below with the dropdown ID you just copied, then paste the script into the JSON editor.

When a number field has text options configured, Benchling automatically generates an additional text column for that field in the data warehouse. Since columns can only contain one type of information, the original column holds the numeric value and the text column holds the text value, depending on the entry’s selected value. The new column is titled {field_name}$text.

Permissions and access control

Permissions determine who can create, edit, and manage Result schemas in your Benchling tenant. Ensuring the right team members have the right level of access helps maintain consistency and data integrity across experiments.

• Only users with admin-level permissions or appropriate feature access can view and modify schema configurations.
• Schema creation, editing, and archiving actions are typically restricted to designated system administrators or Lab Managers.
• If a user doesn’t see the Result schemas option under Feature Settings, they likely need their permissions updated by a workspace or tenant admin.
• API access to schemas (for automation or integrations) also requires API key credentials with appropriate scopes.

Tip: Regularly review your team’s permissions to ensure only intended users can modify schema structures, especially in production environments.