Benchling

Benchling Schemas

Schemas in the API

Schemas in Benchling allow setting custom fields and configuration on several different types of objects throughout Benchling. This is incredibly powerful for bringing structure to your data in Benchling and offers significant control over your data.

The important note for developers building on the API is that schemas are represented in the API and can be leveraged for top level actions such as filtering. This is useful for accessing data in the correct context, but making changes to them can make breaking changes to integrations developed on the API leveraging those capabilities.

Currently they are only able to be retrieved through the API, but not updated or created. They must be created/updated in Benchling's registry settings via the UI.

Schema Fields

Many different Benchling resources support fields (lists of key-value pairs). There are two kinds of fields: schema fields and custom fields

Schema fields can have types that are defined by a resource's schema (e.g. an entity can have a schema that defines particular fields on that entity). These fields have types that define what format the value needs to be.

Custom fields are more free-form than schema fields, and only exist for entities. They do not support different value types, they're all text. They are also not connected to any schema; you can add a custom field with any name to any entity.

Fields Dictionary

All fields are listed as a dictionary, mapping field names to information about the field, e.g.

{
  "Resistance Gene": {
    "isMulti": true,
    "textValue": "Amp",
    "type": "sequence_link",
    "value": ["seq_jdf8BV24"]
  },
  "Description": {
    "isMulti": false,
    "textValue": "Descriptive text",
    "type": "text",
    "value": "Descriptive text"
  }
}

Schema fields (in the example above) will have the following properties in their information:

Field Name

Field Description

value format

type

The type of the field value. Supported types are listed below.

displayName

(Assay schemas only) The name displayed in user interfaces. Assay schema field names must be valid SQL identifiers (all lowercase, no spaces), but they are allowed to have a different, more human-readable name.

string

isMulti

Whether or not the field can have multiple values. This can only be true for some types.

boolean

textValue

The value of the field, serialized to text. This is useful for a quick representation of a more complex value (a list of files, for instance).

text

value

The actual value of the field. This is the only property that's required if you are creating a new field, or patching an existing one. The format of the value depends on the type, and these are listed below.

isRequired

Whether or not the field is required to be filled.

Enforcement of this depends on the resource that has this field. For entities, this is not enforced until the entity is registered.

boolean

archiveRecord

This is null if the field is not archived. If it is archived, this contains an object with the reason key that is a string if it is archived.

null/not null

numericMin

(Float and integer fields only) Minimum allowed numeric value. This is null if there is no minimum value.

float / integer

numericMax

(Float and integer fields only) Maximum allowed numeric value. This is null if there is no maximum value.

float / integer

Because custom fields don't support types, they only have a value property. This means there's also no difference between the dictionary used to create or patch a field and the dictionary that is returned when reading one. An example of custom fields is below:

{
  "Custom field 1": {
    "value": "value 1"
  },
  "Custom field 2": {
    "value": "value 2"
  }
}

Field Types

  • We use null to represent links to deleted items. For example, a field linking to 1 existing sequence and 1 deleted sequence could have the value ["seq_irmfLGBY", null].

Type

Description

Supported resources

isMulti status

Example value

dna_sequence_link

Link to any DNA sequence

Entities

Always true for entities

["seq_irmfLGBY", "seq_NaMPZU9f"]

aa_sequence_link

Link to any AA sequence

Entities

Always true for entities

["prtn_irmfLGBY", "prtn_NaMPZU9f"]

entity_link

Link to any entity with a specified schema

Entities, Requests, Results, Runs

Can be set to true or false

["bfi_irmfLGBY", "seq_NaMPZU9f"]

dropdown

A value taken from a specified dropdown

Entities, Requests, Results, Runs

Always true for entities, always false for requests, results, and runs

["sfso_irHsd89V", "sfso_jV2398sd"]

part_link

Link to a sequence with a specified schema, whose bases are a part of the sequence that has this field.

Sequences

Always true

["seq_irmfLGBY", "seq_NaMPZU9f"]

translation_link

Link to a protein with a specified schema, whose residues are a translation of some of the bases on the sequence that has this field.

Sequences

Always true

["prtn_irmfLGBY", "prtn_NaMPZU9f"]

blob_link

Link to a blob

Requests, Results, Runs

Always false

"168a5fda-8305-4486-af05-ac2bd2439927"

text

Text

All

Always false

"hello world."

long_text

Text (this is no different data-wise from the text field, but in the UI it has a longer input box).

All

Always false

"hello world."

batch_link

Link to a batch on an entity of a specified sequence.

Batches, Requests, Results, Runs

Always true

["bat_oiwe891G", "bat_sad241NM"]

storage_link

Link to a grid, location, or container.

Requests, Results, Runs, Storage

Always false

"plt_f19agmz9"

assay_request_link

Link to an assay request.

Requests, Results, Runs

Always false

faf7c78c-72f2-4737-ab9d-78bdedb19906

assay_result_link

Link to an assay result.

Requests, Results, Runs

Always false

232779bd-7973-4d59-a51d-b5e6da589770

assay_run_link

Link to an assay run.

Requests, Results, Runs

Always false

71a8a7ea-ece6-4928-9ee7-1a131854df43

boolean

Boolean.

Requests, Results, Runs

Always false

false

float

Floating point number.

All

Always false

3.14159265

float (with legal text)

Floating point number
OR
Text that corresponds to the name of a dropdown option in the field's legal text dropdown. (This is only applicable to float fields for which a legalTextDropdownId has been defined in the schema).

Results

Always false

"LLOQ"

integer

32-bit integer.

All

Always false

-105

datetime

RFC 3339 timestamp

Requests, Results, Runs

Always false

2017-05-18T17:49:17.407426+03:00

json

JSON object

Requests, Results, Runs

Parent Links

Parent links are a special kind of entity link field type that can flexibly represent the connection between two schemas. For example, a Mixture can represent both a Recipe and many physical instances of that mixture in the lab (Preps).

This section covers some common uses of Parent links.

Entities

Parent links are often used to represent the link between a physical Lot of some Entity in the lab (the Child entities), and the abstract concept of that entity (the Parent). A common example is a plasmid (parent) and plasmid prep (child).

Mixtures

Parent links are often used to represent the link between a Prep (the child) and the Recipe for that prep (the parent).
In some cases a Prep can reference another Prep as a parent, for example if a mixture is being changed slightly in an iterative process.

Updated 16 days ago

Benchling Schemas


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.