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 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.	Results, Runs	Always false	`false`
`float`	Double precision / 64-bit float.	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.