Request file

The request file, request.yaml, contains the instructions for requesting a subset of data from a data package. The file is created by a Requester through the web application, terminal interface, or even manually (though not recommended). The file is used by an Owner to check and generate the requested data subset. You can read more about the Requester and Owner user types in the Design overview page

The request file is intended to be both human-readable and machine-readable. It should be simple enough for a Requester to understand and, when needed, edit manually. At the same time, it should be structured enough that Propagate can check it against the data package metadata and convert it into an SQL query for generating the requested data subset.

Format

The request file uses YAML. YAML was chosen because it is more readable for manual editing than JSON and less verbose than TOML for lists of columns and row filters.

Structure

The request file contains the following top-level sections:

  • request: Information about this specific request.
  • requester: Information about the person requesting the data.
  • project: Information about the research project that requires the data.
  • data-package: Information about the data package the request applies to.
  • subsets: The requested data subsets, with one item per resource.

Each of these is elaborated on below:

Request

The request includes information about the request itself, such as when and why it was created. This helps an Owner organize and track requests, which is especially beneficial for data packages that receive large volumes of requests.

request:
  datetime-modified: "DATETIME"
  datetime-created: "DATETIME"
  motivation: "TEXT"
  • datetime-modified: When the request was last modified. This can act as an ID which facilitates referring to a specific iteration of a request, e.g. in dialog between the Owner and Requester. Precision to the second should be sufficient.
    • Note that this field is automatically populated when the request is saved via a user interface (be it the web app or the TUI). If the request is edited manually, it must be updated manually.
    • The format should be ISO 8601, e.g. 2026-07-06T01:45:34Z of the current time without time zone information. Propagate assumes that it is very rare that Requesters are outside of the Owner’s timezone and that it is mostly used by people within the same group or institution that are assumed to be using Propagate together.
  • datetime-created: When the first iteration of the request was created. It is also set at UTC and in ISO 8601 format.
  • motivation: Explanation for why the requester’s project needs access to this data subset. This is used by the Owner to check whether the requested data is relevant to the project. The motivation is particularly needed for human health data since there are legal requirements (e.g. GDPR) to declare for what purposes the data is used.

Requester

The requester section describes who is requesting the data. This person doesn’t strictly have to be the one working with the data, but they should serve as the main point of contact for the Owner.

requester:
  name: "TEXT"
  email: "TEXT"
  • name: The name of the requester.
  • email: The email of the requester.

Project

The project section contains information about the research project that requires the data. A project is defined as a body of work that results in a research output, e.g. a paper, report, website, dashboard, or analysis. This could be a part of a PhD student’s thesis or a collaboration research project for a group of researchers. This field is necessary to ensure that the data requested is aligned with what it is intended to be used for, which can be a legal requirement (e.g. in GDPR).

project:
  name: "TEXT"
  title: "TEXT"
  description: "TEXT"
  • name: Think of name as a GitHub repository name, which is meant for consumption by both humans and machines. Use lowercase letters and hyphens where possible, e.g. my-research-project. name is meant to be an indirect identifier which needs to be combined with other information such as data package, requester, and project name to uniquely identify a request. It is also meant to be legible enough to display in different areas/different ways.
  • title: A longer human-readable project title, e.g. My research project. This could be used by the Owner to publicly display the data package requests.
  • description: A summary of the project, including details like background, rationale, basic methods, and potential research questions. This information, combined with the motivation, is mainly to help the Owner ensure that the data requested matches what it will be used for.

Data package

The data-package section identifies the data package the request applies to. This information will be automatically populated from the data package metadata when creating a request via the web application or the TUI.

data-package:
  name: "TEXT"
  version: "X.Y.Z"
  • name: A human readable name to refer to. It is lowercased and doesn’t include any spaces. E.g., my-data-package.
  • version: Helps the Owner detect which version of the data package the request is for.