Managing Metadata with Curator

About

Curator provides a spreadsheet-style grid on the Synapse website that offers a familiar row-and-column layout used in many data management tools. This interface allows you to add metadata to describe files and enter data into records, such as participants, subjects, cases, or other entities relevant to your project.

In addition to manual editing, Curator offers an AI-powered chat assistant that can help you complete your metadata tasks more efficiently. The assistant can guide you through metadata requirements, suggest appropriate values, and help populate fields based on your project context. This approach is commonly referred to as human-in-the-loop AI, where the system leaves final decisions and edits under human control.

There are two core concepts to keep in mind: file-based metadata and record-based metadata.

• File-based metadata is information attached to files you upload to Synapse, stored as Synapse Annotations. Synapse annotations refer to key-value pairs that describe important details about a file. If you have used Synapse before, you may recognize annotations as the metadata associated with the tag icon shown here . Annotations are used by downstream systems (for example, Synapse data portals) to support tasks like search and filtering, which is why well-annotated data is important.
  
  In file-based metadata spreadsheets, the leftmost columns are id and name. These are system-generated and should not be edited.

  • id corresponds to the Synapse ID, which uniquely identifies files, folders, datasets, and other entities, and follows the format syn plus an eight-digit number.

  • name corresponds to the file name.
    
    Columns to the right of id and name capture additional metadata defined by the associated schema and are displayed as the header row. The table below shows an example for RNA sequencing FASTQ files, annotated with metadata fields such as assay, tissue, species, file type, and patient ID.

2. Record-based metadata describe study entities such as participants, samples, or specimens. Each row (referred to as a record) should represent a single entity and must include a unique identifier (such as the patient_id shown in the table below) which serves as the upsert key. When new records are uploaded, rows with the same upsert key overwrite and update the existing record, while rows with new upsert keys are appended as new records. As shown in the table below, record-based metadata capture additional clinical context (for example, diagnosis, age bracket, and sex) for the files listed above. Record-based metadata are stored in a separate table so that multiple files can be linked to the same participant or sample without repeating the same information. This keeps metadata consistent and easier to update.

💡 Test your knowledge!

Requirements for using Curator

To use Curator, you must:

• Create a Synapse account

• Complete the Synapse Certification Quiz

• Turn on Experimental Mode (found at the bottom right of any synapse.org page)

Setting up Curator

Contributors on the free basic plan who manage their own projects can set up Curator programmatically using the instructions provided here. Contributors on paid self-managed plans or data coordination plans designed for larger consortia will have project setup handled by Sage, with Curator enabled on their behalf.

If you are part of a Data Coordination plan and have questions or need support, please contact your consortium’s service desk:

• AD Knowledge Portal / Exceptional Longevity Help Desk

• ARK Portal Help Desk

• HTAN Help Desk

• MC2 Help Desk

• NF-OSI Help Desk

If neither of these apply, please submit questions to the Synapse Help Desk

Navigating to Curator

Once Curator is enabled and at least one metadata task exists, the Metadata tab appears on the Synapse project page. This tab is the central place to see metadata sheets associated with your project.

What Are Tasks?

Curator introduces the concept of tasks in Synapse. A task is an action item that guides you through completing a specific set of required or recommended steps for your project or data.

How Tasks Relate to Your Project Files

Metadata tasks are directly connected to your project’s file structure.

When you navigate to the Files tab, you will see folders corresponding to each metadata task. The type of folder depends on the metadata workflow used.

Conceptual Diagram of a Synapse Project

Project
│
├── Metadata (Tab)
│     ├── Task: Biospecimen Metadata
│     └── Task: File-Level Metadata
│
└── Files (Tab)
      ├── Biospecimen_Metadata_Task/
      │     └── Biospecimen_RecordSet (table)
      │
      └── File_Metadata_Task/
            ├── file_001.fastq
            ├── file_002.fastq
            └── file_003.fastq

If you are unsure which task to complete, or if you do not see an expected task, please contact your data manager or project administrator for guidance.

Permissions and Collaboration

Curator is designed to promote collaboration by ensuring that everyone on a project sees a shared, consistent set of metadata tasks. Metadata tasks are project-level objects, not tied to a single individual, which allows team members to work together, review progress, and maintain alignment throughout the metadata curation process.

As of December 2025, the Curator grid does not support simultaneous editing by multiple users.

• Only one working session can be applied at a time

• When changes are saved, the most recent session overwrites previous changes

• The saved state becomes the new set of Synapse annotations

• Each grid session URL is unique to the signed-in Synapse user, so copying or sharing the grid URL will not work. To direct a colleague to a grid session, it is recommended to share the project’s Metadata tab instead.

Access to metadata tasks follows Synapse project permissions, so existing collaboration models remain intact.

Working in a Grid Session

There are two ways to start a grid session:

1. From the Metadata, click Working Copy under the Actions menu.

2. Alternatively, click the Data Type to navigate to the specific Synapse entity, then select Create New Working Copy from the menu (three horizontal lines).

3. Either method initializes a grid session. For file-based metadata, the grid displays the list of files in the leftmost column. For record-set data, the grid displays all records in the dataset, either populated from a previous session or with empty cells if no metadata has been entered yet. Column headers indicate the fields or properties that need to be completed.

• Blue column headers = required fields

• White column headers = optional fields

• Pink cells = missing or invalid values

• White cells = validated values
  
  

  

  
  

4. Enter metadata by clicking directly into a cell and typing a value. For fields with a controlled vocabulary, click the cell and select one or more values from the drop-down list.

   The grid supports the following actions:

   • Select + Add to create new rows.

   • Right-click a cell (or Control + Click) to open the context menu, which includes:

     • Copy

     • Cut

     • Paste

     • Insert row below

     • Duplicate row

     • Delete row

   • Scroll horizontally to view all available fields.

   • Upload a CSV file to populate the grid with metadata.

   • Select View Validation Schema (JSON) at the top of the page to inspect the underlying schema (advanced users).

Uploading a CSV

If you prefer to complete your data in another system (for example, Excel or Google Sheets), you can download a CSV template and upload it back to the grid.

1. Navigate to the Metadata tab.

2. Click the link under Data Type.

3. Click the download icon :d: and Export Table to export the table as a CSV.

4. Open the CSV in your preferred tool and complete it offline.
   Important:Do not change the column headers.

5. When you’re ready to upload your changes, navigate to a grid session.

6. Click Upload and select your completed CSV file.

AI Grid Assistant

The Grid Assistant is an AI-powered chat assistant designed to help you curate, clean, validate, and populate tabular data directly within a grid. It understands the grid’s schema and can analyze selected rows or the entire dataset to provide guidance, corrections, and transformations.

The assistant is especially useful when working with structured data that must conform to specific validation rules or when you want to quickly populate a grid using a project description or other large blocks of text.

Accessing the Grid Assistant

To open the AI Chat Assistant:

1. Navigate to the grid.

2. Click the Open Chat button in the upper-right corner of the grid. The chat panel will open, allowing you to ask questions or give instructions related to the grid.

3. To close the chat, click the × in the upper-right corner of the chat panel. Closing the chat preserves your current conversation.

4. If you leave the page or refresh your browser, the chat session will end. A new chat session will start when you reopen the Grid Assistant.

5. Grid Assistant can make mistakes, so please check all work prior to submitting!

What the Grid Assistant Can Help With

• Identify errors, missing values, and duplicate records in the grid.

• Normalize and clean inconsistent or poorly formatted data.

• Explore, filter, and summarize data in the grid.

• Create new columns or derive values from existing data.

Example Prompts:

• Can you check the selected rows for schema validation errors and explain what’s wrong?

• These rows have inconsistent date formats in the sample_date column - can you fix this?

• I’m seeing errors in the species column for this data. What’s the issue, and can you fix the selected rows?

• For the selected rows, can you generate a sample_id by combining project_id and specimen_number?

• Are there any common issues across the selected rows that I should address before submission?

Not Acceptable Uses of AI

Do not submit data to the AI Assistant containing personal identifiers, including but not limited to:

• Names of individuals

• Email addresses

• Usernames or account IDs

• ORCID iDs

• Phone numbers

• Institutional login credentials

• Any direct or indirect identifiers that could be used to identify a person

💡 Tips

• Be specific about which rows or columns you want the assistant to work on.

• Use prompt templates for repeatable workflows.

• Review suggested changes before applying them to ensure correctness.

Metadata Requirements

Consortium or Funder Requirements

If you are part of a larger consortium or are working under a specific funder, metadata requirements are often already defined for you. These requirements ensure consistency across datasets and help make data interoperable within a research domain.

You do not need to configure or apply these requirements yourself. When you fill out the Curator grid, the appropriate metadata schema is automatically applied for you. It can be helpful to be aware of these metadata requirements ahead of time, so you know what information to collect during data generation and preparation.

Below are examples of consortium-managed metadata dictionaries and data models that Curator uses behind the scenes:

• NF Metadata Dictionary

• AMP-AD Metadata Dictionary

• ARK Portal Data Model Dictionary

• MC2 Center Data Models Explorer

• ELITE Metadata Dictionary

Individual Synapse Users

If you are an individual Synapse user and are not part of a larger consortium, we plan to make this easier in the future by offering a set of standard metadata schemas that you can choose from. These schemas will cover common data types and research workflows and will help guide you in providing clear, consistent metadata when uploading your data.

For now, if you’re interested in learning more or working with a more advanced setup, you can explore these resources:

• Curator MVP setup via Python, for defining custom metadata structures

• JSON Schemas to see how metadata fields and validation rules are defined behind the scenes

Validating

The grid editor checks your entries as you type and points out missing or incorrect information. Highlighted cells and messages show you what needs attention.

You can still click Apply Changes even if there are messages. This is on purpose, so you can save your work when some information isn’t available yet (for example, if you don’t know a required value or don’t see the right option in the list).

Where to See Validation Errors

• Row Indicator (Left Panel): A highlighted row indicator means at least one value in that row is missing or invalid.

• Highlighted Cells: Highlighted cells show exactly which values are missing, invalid, or incorrectly formatted.

• Validation Message Panel (Bottom of Screen): A yellow panel displays explanations of validation errors. An example is shown below:

Resolving Validation Errors

Saving

Edits are saved in real time as you enter information in the form. If you leave the page and return later, your information will still be saved.

However, these changes are not committed to Synapse as final annotations until you click Apply Changes.

If the update is successful, a green bar at the bottom of the screen will confirm that the sheet has been successfully updated.

Viewing Submitted Metadata

To see file-based metadata or record-based metadata in a tabular CSV form:

1. Navigate to the Metadata tab.

2. Click the entity link under Data Type to open a preview of the full CSV submitted to Synapse.

3. From the preview screen, you can download the CSV if needed.

File-based metadata annotations also become “Synapse annotations” and are visible with each individual file.

1. Navigate to the Files tab in the Synapse project.

2. From the folder tree, navigate to the folder associated with the records.

3. Hover over the tag icon :ann: next to an individual file name to view its annotations.

   • A yellow tag :y: indicates that one or more annotations do not meet the schema requirements and should be corrected.

4. To see a complete list, click the file entity and click the :annotation: icon on the top right of the entity page.

Annotations associated with a record set are also visible on the file-tree view.

1. Navigate to the Files tab in the Synapse project

2. Click the appropriate folder associated with the records.

3. Select the record set entity :re: , which will open a preview displaying the associated metadata.

Troubleshooting

Reporting a Bug, Requesting a Feature, or Getting Help

If you run into an issue, have a question, or would like to request a new feature for Curator, please submit a support ticket to the Synapse Help Desk

When submitting your request, please include the word “Curator” in the Summary field so we can quickly route and triage your request.

To help us resolve your issue faster, include:

• A brief description of the problem or request

• The synapse ID (syn########) of relevant projects, folders, files

• Any error messages you saw

• Screenshots or recordings, if available

For questions related to specific projects or Data Coordination Plans, please contact your consortium’s service desk instead:

• AD Knowledge Portal / Exceptional Longevity Help Desk

• ARK Portal Help Desk

• HTAN Help Desk

• MC2 Help Desk

• NF-OSI Help Desk

Frequently Asked Questions

What features are available today?

Below is a summary of features available today and under construction.

What happens if two users are on the same grid in different browser sessions?

At this time, Curator does not indicate whether another user is currently working in the same grid. While metadata tasks are shared at the project level, the grid does not support real-time presence or simultaneous editing. The most recent saved session determines the current set of Synapse annotations, so we recommend coordinating with your team to avoid overlapping edits.

The value I need is not in the valid-value list. What should I do?

You can still click Apply Changes even if the value you need is not in the valid-value list. However, we recommend notifying your data manager/consortium contact that the term is missing from the metadata dictionary so it can be reviewed and added if appropriate.

Is Synapse updated immediately as I edit the grid?

No. The grid functions as a draft workspace. Your edits are saved as you work, but metadata is not submitted to Synapse until you click Apply Changes.