RWL Schema Documentation¶
rwl_actors.proto¶
RWL Actors and Publications Schema
Who and What was Produced?
This file defines the actors (individuals or organizations) involved in the RWL activities and the publications that result from their work.
Overview of Objects:
| Object | Description |
|---|---|
| Actor | An individual, group, or institution participating in a lab. |
| Publication | A publication resulting from the work in a lab or experiment. |
Actor¶
An Actor represents a participant or stakeholder in a Lab.
| Field | Type | Description |
|---|---|---|
| pkey | CompositeKey | Primary Key. A unique identifier for the actor. |
| name | string | The name of the actor. |
| sector | Actor.Sector | The actor's primary sector. |
| description | string | A description of the actor and their role in the lab. |
| contact_data | string | Contact information for the actor. Can be an email, address, etc. |
| link_url | string | A URL to the actor's website or profile page. |
Publication¶
A Publication is a citable output, such as an article, report, or dataset.
| Field | Type | Description |
|---|---|---|
| pkey | CompositeKey | Primary Key. A unique identifier for the publication. |
| title | string | The title of the publication. |
| citation | string | A full citation for the publication (e.g., in APA or BibTeX format). |
| link_url | string | A URL to access the publication, if available (e.g., a DOI link). |
| lab_pkey | CompositeKey | Foreign key linking this publication to the Lab it originated from. |
| experiment_pkey | CompositeKey | Optional foreign key linking this publication to a specific Experiment. |
Actor.Sector¶
The societal sector the actor belongs to.
| Name | Number | Description |
|---|---|---|
| UNKNOWN | 0 | |
| SOCIETY | 1 | |
| SCIENCE | 2 | |
| BUSINESS | 3 | |
| ADMINISTRATION | 4 |
rwl_common.proto¶
Common Structures for the Real-World Lab (RWL) Schema
This file defines common, reusable messages used across the RWL schema. These messages are the fundamental building blocks that enable data from different sources to be integrated while maintaining clear provenance. They are primarily used for creating unique and linkable data entities.
Overview of Objects:
| Object | Description |
|---|---|
| Origin | A reference to a specific data source, project, or database. |
| CompositeKey | A unique key to identify any object across different data origins. |
CompositeKey¶
A Composite Key is used as the primary key for all major objects in the schema. It creates a globally unique reference by combining an Origin (the source of the data) and the object's original unique ID from within that source. This prevents ID collisions when merging data from multiple sources and ensures every piece of data is traceable back to its original context.
| Field | Type | Description |
|---|---|---|
| origin | Origin | Specifies the source system or project where this object's data originated. |
| id | string | The unique identifier (primary key) of the object within its original source. This could be a database integer ID, a UUID, or any other unique string used by the source system. |
Origin¶
An Origin is a reference to the unique source of the data, such as a specific Real-World Laboratory (RWL) project, a research database (e.g., Grist), or a specific data import (e.g., "HCU Case Study Imports"). It allows the schema to differentiate between data that might come from separate, parallel research efforts.
| Field | Type | Description |
|---|---|---|
| origin_id | int32 | A unique integer ID used internally within this schema to refer to a data origin. This provides a compact and efficient way to reference the source. Example: 1 could represent the "ExU-Präsentation" dataset. |
| name | string | The descriptive, human-readable name of the Origin. Example: "GLOCULL Project Case Study Data". |
rwl_context.proto¶
RWL Context Schema
What is Context?
This file defines the contextual factors that surround and influence Real-World Labs and their Experiments. It captures everything from the high-level sustainability problems being addressed to specific environmental, political, and social factors.
Overview of Objects:
| Object | Description |
|---|---|
| LabContext | The external and internal context specific to a Lab. |
| ExperimentContext | The external context specific to an Experiment. |
ExperimentContext¶
The ExperimentContext is intended to hold any external context factors that are uniquely relevant to a specific experiment, separate from the broader lab context.
| Field | Type | Description |
|---|---|---|
| pkey | CompositeKey | Primary Key. A unique identifier for this context entry. |
| experiment_pkey | CompositeKey | Foreign key linking this context directly to an Experiment. |
| external_context_description | string | A description of the external context specifically relevant to this experiment. |
LabContext¶
A LabContext encapsulates the rich contextual details of a specific Lab.
| Field | Type | Description |
|---|---|---|
| pkey | CompositeKey | Primary Key. A unique identifier for this context entry. |
| lab_pkey | CompositeKey | Foreign key linking this context directly to a Lab. |
| motivation | LabContext.Motivation | The lab's motivation and sustainability focus. |
| external_factors | LabContext.ExternalFactors | The external factors influencing the lab. |
| scope_and_governance | LabContext.ScopeAndGovernance | The lab's operational scope and governance. |
LabContext.ExternalFactors¶
Describes the external factors influencing the lab's environment. Maps to "Context_External Context" from the schema table.
| Field | Type | Description |
|---|---|---|
| environmental | string | Relevant environmental factors (e.g., climate, soil type, vegetation). |
| financial_economic | string | Relevant socio-economic factors (e.g., taxes, unemployment, economic diversity). |
| legal_political | string | Relevant legal or political factors (e.g., laws, regulations, public participation). |
| organisational_capacity | string | Organisational or capacity factors (e.g., knowledge, skills, networks). |
| social_cultural | string | Relevant socio-cultural factors (e.g., history, education, social norms). |
| technical_infrastructure | string | Relevant technical or infrastructure factors (e.g., transport, energy, housing). |
LabContext.Motivation¶
Contains details about the lab's purpose and the problems it addresses. Maps to "Lab_Motivation and sustainability understanding" from the schema table.
| Field | Type | Description |
|---|---|---|
| sustainability_problem | string | A detailed description of the concrete sustainability problem the lab addresses. |
| research_motivation_and_objectives | string | The research motivation and specific objectives that drive the lab's work. |
| sustainability_understanding_adopted | string | The specific understanding of sustainability that the lab adopts. |
| sustainability_understanding_process | string | Describes the process through which the sustainability understanding was reached. |
| sustainability_understanding_changes | string | Notes on how the understanding of sustainability deepened or changed during the lab. |
LabContext.ScopeAndGovernance¶
Defines the governance, operational space, and timeline of the lab. Maps to "Lab_Governance", "Lab_Space", and "Lab_Temporal Scope".
| Field | Type | Description |
|---|---|---|
| governance_system | string | The systems involved in steering the lab (e.g., public, private, research). |
| spatial_scope | string | The spatial scope of the lab’s activities, including geographical boundaries. |
| temporal_scope | string | The temporal scope of the lab’s activities, including its overall duration. |
| foundation_and_previous_work | string | A description of crucial previous work or foundational projects. |
| long_term_perspective | string | The lab's future outlook and long-term perspective. |
rwl_core.proto¶
Core RWL Entities: Lab, Experiment, and Intervention
Core Concepts
This file defines the central entities of the RWL schema, representing the different levels of activity in the research. The structure is based on the conceptual model of disambiguating Context, Lab, and Experiment as described in Bernert et al. (2023), "Cross-case knowledge transfer...".
Overview of Objects:
| Object | Description |
|---|---|
| Lab | The overarching framework or environment for research. |
| Experiment | A specific experiment conducted within a Lab. |
| Intervention | A specific intervention, which can be part of an Experiment. |
Experiment¶
Experiments are deliberately designed and evaluated interventions in real-world contexts and are the core research method of transformative lab approaches. They are collaboratively conducted and partially controlled within the lab space. They produce evidence, knowledge, and other outputs that are then evaluated and processed.
| Field | Type | Description |
|---|---|---|
| pkey | CompositeKey | Primary Key. A unique identifier for the experiment. |
| general_information | string | General information about the experiment, its scope, and objectives. |
| inputs | string | Describes the enabling factors and resources invested in the experiment. This corresponds to the 'Inputs' category in the case reporting scheme, covering aspects like awareness, commitment, expertise, trust, and support. |
| process | string | Describes how the experiment was designed and conducted. This corresponds to the 'Processes' category, covering the sequence of actions, methodology, collaboration, reflexivity, and transparency. |
| outcome | string | Describes the broader effects and contributions to sustainability. This corresponds to the 'Outcomes' category, covering contributions to socio-ecological integrity, livelihood sufficiency, equity, and resource maintenance. |
| output | string | Describes the direct, tangible results and generated products from the experiment. This corresponds to the 'Outputs' category, covering built capacities, actionable knowledge, and changes in physical or social structures. |
| lab_pkey | CompositeKey | Foreign key to the Lab this experiment belongs to. |
| solution_pkey | CompositeKey | Foreign key to a Solution associated with this experiment. |
| start_date | google.protobuf.Timestamp | The date and time when the experiment officially began. |
| end_date | google.protobuf.Timestamp | The date and time when the experiment officially ended. |
| duration | google.protobuf.Duration | The total duration of the experiment. |
Intervention¶
An Intervention is a specific, concrete action or set of actions taken within the real-world setting. In the context of this schema, an intervention is often the practical component of what is being studied in an Experiment.
| Field | Type | Description |
|---|---|---|
| pkey | CompositeKey | Primary Key. A unique identifier for the intervention. |
| general_information | string | General information about the intervention, its goals, and its context. |
| inputs | string | Describes the enabling factors and resources invested in the intervention (e.g., commitment, expertise, support). |
| process | string | Describes how the intervention was designed and implemented (e.g., sequence of actions, methodology, collaboration). |
| outcome | string | Describes the broader effects and contributions of the intervention (e.g., on socio-ecological integrity, equity, etc.). |
| output | string | Describes the direct, tangible results and products from the intervention (e.g., built capacities, actionable knowledge). |
| experiment_pkey | CompositeKey | Foreign key to the Experiment this intervention is a part of. |
| lab_pkey | CompositeKey | Foreign key to the Lab this intervention belongs to. |
| solution_pkey | CompositeKey | Foreign key to a Solution associated with this intervention. |
| start_date | google.protobuf.Timestamp | The date and time when the intervention began. |
| end_date | google.protobuf.Timestamp | The date and time when the intervention ended. |
| duration | google.protobuf.Duration | The total duration of the intervention. |
Lab¶
A Lab is a collaborative 'space' created by scientists and actors from other societal domains to co-produce sustainability pathways or solutions. Within the lab, the processes governing its design, purpose, and organisation are continuously negotiated. It provides the structure and framing in which sustainability experiments are developed and carried out.
| Field | Type | Description |
|---|---|---|
| pkey | CompositeKey | Primary Key. A unique identifier for the lab. |
| name | string | The official name of the lab. |
| image_url | string | URL to a representative image of the lab. |
| description | string | A general, high-level description of the lab, its purpose, and composition. |
| link_url | string | A link to the lab's main website or information page. |
| topics | string | A list of topics or keywords associated with the lab. |
| innovation_focus | Lab.InnovationFocus | The primary innovation focus of the lab. |
| is_finished | bool | Indicates whether the lab's activities have been completed. |
| start_date | google.protobuf.Timestamp | The official start date of the lab. |
| end_date | google.protobuf.Timestamp | The official or expected end date of the lab. |
| duration | google.protobuf.Duration | The total duration of the lab. Can be used if specific start/end dates are not known or relevant. |
| responsible_institution | string | The primary institution responsible for the lab, including contact data. |
| involved_institutions | string | A list of other institutions involved in the lab. |
| financing_info | string | Information about the financing of the lab. |
| involved_actors_pkey | CompositeKey | A list of pkeys for Actors involved in this lab. |
| resulting_publications_pkey | CompositeKey | A list of pkeys for Publications resulting from this lab. |
Lab.InnovationFocus¶
Enum to classify the primary type of innovation the lab focuses on.
| Name | Number | Description |
|---|---|---|
| UNKNOWN | 0 | |
| TECHNICAL | 1 | |
| SOCIAL | 2 |