Introduction

In OpenSpecimen, Participant, Visit, and Specimen pages display fields one per line by default.

When there are many fields, users need to scroll more. Small fields (like dates or quantity) take unnecessary space, and some labs prefer a compact layout similar to older systems. To improve this, OpenSpecimen provides Layout Configuration in JSON.

This allows users to:

Arrange fields on the screen
Group related fields together
Organize sections clearly

The goal is to make data entry faster and cleaner.

Where to Configure Layout

Add the layout section inside the dictionary section of the CP/System JSON, after the "fields" block.

Structure example:

{
  "dictionary": {
    "fields": [
      ...
    ],
    "layout": [
      ...
    ]
  }
}

What You Can Configure

1. Group Fields in One Row

Place related fields on the same line, such as First Name and Last Name or Quantity fields, to reduce scrolling and save space.

2. Create Sections

Organize related fields under a section title (e.g., Collection Details, Tissue Details). This improves clarity and structure.

3. Conditional Sections (Deprecated in v11.x)

Earlier versions allowed showing sections based on field values. (e.g., show Tissue Details only when Specimen Type = Fresh Tissue).

Supported Pages

Layout configuration can be applied to:

Participant Add/Edit page
Visit Add/Edit page
Specimen Add/Edit page

Example

You can refer to the example below to configure the layout in the JSON file.

"layout": [
        {
          "rows": [
         [
            "cpr.registrationDate",
            "cpr.participant.birthDate"
          ],
          [
            "cpr.participant.firstName",
            "cpr.participant.lastName"
         ],
         [
            "cpr.participant.gender"
         ],
         [
           "cpr.participant.pmis"
         ],
         [
           "visit.name",
           "visit.surgicalPathologyNumber"
         ],
         [
           "visit.clinicalDiagnoses",
           "visit.site"
         ],
        
         [
           "visit.visitDate"
         ],
         
         [
           "visit.comments"
         ],
         [
           "specimen.type"
         ],
         [
           "specimen.initialQty",
           "specimen.availableQty"
         ],
         
         [
            "specimen.comments"
         ]
       ]
     }, {
       "title": "Tissue Details",
       "rows": [
         [
           "specimen.anatomicSite",
           "specimen.pathology"
         ],
         [
          "specimen.laterality"
         ]
       ]
       }, {
         "title": "Collection and Received Event Details",
         "rows": [
         [
           "specimen.collectionEvent.time",
           "specimen.receivedEvent.time",
           "specimen.createdOn"
         ],
         [
           "specimen.receivedEvent.user",
          "specimen.collectionEvent.user"
         ]
       ]
     }
   ]

Grouping of fields on participant page:

Grouping of fields on the visit page:

Grouping of fields on the specimen page along with a section (For example: Collection & Received Event section)

Example JSON

Download

Layout - Arrangement & Grouping of Fields