Skip to content

Spec Builder

The Spec Builder is where you design custom metadata specifications — your own entity types, fields, relationships, and validation rules — instead of using a built-in profile. Open it from Specs in the header.

A specification exists in two states:

  • Draft — editable; listed under My Drafts.
  • Published — an immutable released version; listed under Published Specifications.

Creating a specification

  1. On the Specs page, click + New Specification.
  2. Choose how to start:
  3. From Scratch — an empty specification.
  4. From Template — start from a provided template.
  5. Import YAML — upload an existing specification file (see Publishing and sharing).
  6. The draft editor opens.

The draft editor

The editor combines an entity tree, a diagram (ERD) canvas, and a form editor, with Profile, Rules, Comments, and Sharing tabs in the sidebar.

Entities

Click + Entity on the canvas to add an entity, then click an entity to edit it. From the entity editor you can rename the entity and mark one entity as the specification's root.

Fields

Add fields to an entity with + Field. Each field has:

Property Purpose
Name The field's identifier
Type string, integer, date, ontology_term, entity, list, and others
Required Whether a value is mandatory
Description Help text
Ontologies For ontology-constrained fields, the source ontologies

Relationships

Relationships are expressed through fields whose type references another entity:

  • Use type entity for a one-to-one relationship (for example, Study has one principal investigator).
  • Use type list for a one-to-many relationship (for example, Investigation has many Persons).

Set the field's Related Entity to the target entity. A list field also defines a parent–child hierarchy: the related entity appears as a child in the entity tree.

Relationship Field type Related entity
Investigation has many Persons list Person
Study has one principal investigator entity Person
Person belongs to an Organization entity Organization

Saving

Click Save to persist draft changes. Each edit to an entity, field, or rule is persisted as you make it; Save records the draft as a whole.

A save rewrites the draft's entire specification, so it is refused when the draft has changed elsewhere since you opened it — in another tab, or by a collaborator who has access to it. You get "This spec changed somewhere else since you opened it" rather than a success, because applying your copy would silently discard the other change. Reload the page to pick up the current version and reapply your edit.

Next