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:

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].

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.