The .pb File Format

The data concerning one instance of participatory budgeting is to be stored in a single UTF-8 text file with the extension .pb. The content of the file is to be divided into three sections:

  • META section with general metadata like the country, budget, number of votes.
  • PROJECTS section with projects costs and possibly some other metadata regarding projects like category, target etc.
  • VOTES section with votes, that can be in one of the four types: approval, ordinal, cumulative, scoring; and optionally with metadata regarding voters like age, sex etc.

Each section starts with a title line (one of META, PROJECTS, VOTES), followed by a column header line which is a semicolon-separated list of the names of the columns used in the section (for the META section this must be key;value, for the other sections it depends on which information is available), followed by several lines encoding the data. 

META
key; value
description; Municipal PB in Wieliczka
country; Poland
unit; Wieliczka
instance; 2020
num_projects; 5
num_votes; 10
budget; 2500
rule; greedy
vote_type; approval
min_length; 1
max_length; 3
date_begin; 16.09.2023
date_end; 04.10.2023
PROJECTS
project_id; cost; category
1; 600; culture, education
2; 800; sport
4; 1400; culture
5; 1000; health, sport
7; 1200; education
VOTES
voter_id; age; sex; vote
1; 34; f; 1,2,4
2; 51; m; 1,2
3; 23; m; 2,4,5
4; 19; f; 5,7
5; 62; f; 1,4,7
6; 54; m; 1,7
7; 49; m; 5
8; 27; f; 4
9; 39; f; 2,4,5
10; 44; m; 4,5

Although this is not a single standard CSV file, the format behaves similarly. Each .pb file consists of three sections (meta, projects, and votes), each structured like a separate CSV table — with different numbers of columns per section. Because of this structure, the format follows standard CSV conventions, meaning that special characters are properly escaped using double quotes.

Values are separated by a semicolon (;). If a field contains a semicolon, it is enclosed in double quotes ("). Double quotes inside a field are escaped by doubling them (""). Fields that do not contain special characters (like ; or ") are left unquoted.

For example, in the poland_wroclaw_2017_.pb file:

18;1000000;8640;Rowerowy Wrocław 2017;category
50;1000000;10796;"Zielona rowerowo-piesza obwodnica Wrocławia; ETAP II";category
499;1000000;3949;"""Konikowo"" - Budowa autorskiego placu zabaw";category

Detailed Description

The red part is obligatory.

All fields are provided as key:value pairs.

        * we use integers instead of booleans for flag values (such as 1 and 0) as this approach provides more flexibility. For example, a project can be either selected (1) or not (0). But there are cases where a project is selected for another reason, such as an error made by the company conducting the voting process. In such cases, we can assign a special value, like 2, and explain it in a comment.