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 Schema fields 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 NameField Descriptionvalue format
typeThe 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
isMultiWhether or not the field can have multiple values. This can only be true for some types.boolean
textValueThe 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
valueThe 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.
isRequiredWhether 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
archiveRecordThis 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].
TypeDescriptionSupported resourcesisMulti statusExample value
dna_sequence_linkLink to any DNA sequenceEntitiesAlways true for entities["seq_irmfLGBY", "seq_NaMPZU9f"]
aa_sequence_linkLink to any AA sequenceEntitiesAlways true for entities["prtn_irmfLGBY", "prtn_NaMPZU9f"]
entity_linkLink to any entity with a specified schemaEntities, Requests, Results, RunsCan be set to true or false["bfi_irmfLGBY", "seq_NaMPZU9f"]
dropdownA value taken from a specified dropdownEntities, Requests, Results, RunsAlways true for entities, always false for requests, results, and runs["sfso_irHsd89V", "sfso_jV2398sd"]
part_linkLink to a sequence with a specified schema, whose bases are a part of the sequence that has this field.SequencesAlways true["seq_irmfLGBY", "seq_NaMPZU9f"]
translation_linkLink to a protein with a specified schema, whose residues are a translation of some of the bases on the sequence that has this field.SequencesAlways true["prtn_irmfLGBY", "prtn_NaMPZU9f"]
blob_linkLink to a blobRequests, Results, RunsAlways false"168a5fda-8305-4486-af05-ac2bd2439927"
textTextAllAlways false"hello world."
long_textText (this is no different data-wise from the text field, but in the UI it has a longer input box).AllAlways false"hello world."
batch_linkLink to a batch on an entity of a specified sequence.Batches, Requests, Results, RunsAlways true["bat_oiwe891G", "bat_sad241NM"]
storage_linkLink to a grid, location, or container.Requests, Results, Runs, StorageAlways false"plt_f19agmz9"
assay_request_linkLink to an assay request.Requests, Results, RunsAlways falsefaf7c78c-72f2-4737-ab9d-78bdedb19906
assay_result_linkLink to an assay result.Requests, Results, RunsAlways false232779bd-7973-4d59-a51d-b5e6da589770
assay_run_linkLink to an assay run.Requests, Results, RunsAlways false71a8a7ea-ece6-4928-9ee7-1a131854df43
booleanBoolean.Results, RunsAlways falsefalse
floatDouble precision / 64-bit float.AllAlways false3.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).
ResultsAlways false"LLOQ"
integer32-bit integer.AllAlways false-105
datetimeRFC 3339 timestampRequests, Results, RunsAlways false2017-05-18T17:49:17.407426+03:00
jsonJSON objectRequests, 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.