Contest Archive Format

This page describes the archive format for a contest. It is developed in parallel with, and makes heavy use of, the Contest API.

There are several reasons that contest information will be stored on disk, including:

• As configuration used to initialize a CCS
• As an archive of what happened in a contest
• As an archive for replaying a contest, either for testing contest tools or for teams to compete against live data
• As a base for offline analysis

This standard lays out the relative location and format of each type of contest-related information when reading or writing to disk. The top level structure is inspired by the Contest API structure.

Archive contents

The package consists of a single directory containing files as described below, or alternatively, a ZIP compressed archive of the same files. It is strongly recommended that the name of the directory or the base name of the archive match the contest ID, if a contest ID is specified.

All JSON and NDJSON files and file directories map to endpoints of the Contest API in the following way.

The format of the JSON returned from <endpoint> is accepted as the contents of <endpoint>.json (or .ndjson in the case of event-feed.ndjson). For some files it could make sense to store multiple versions of the file. If so the alternate versions must be stored as <endpoint>.<version>.[nd]json. One example of this could be the judgements from a shadow CCS, which should be stored as judgement.shadow.json. Some fields that are required in the contest API are optional in this file format, to support some non-contest use cases.

Also, all files referenced from the JSON of endpoints are stored in the <endpoint> directory. As such the file reference fields are not required. They are allowed to be included, so that post processing of API output is not needed, even if the URIs contained may not work after a contest (e.g. because they refer to resources on a local network that is no longer available).

In summary, if a system supports the Contest API it is very simple to export a correct archive, but it is not required to support the contest API to be able to use this archive format.

The problem package is not available from the contest API but is stored using a similar naming convention.

JSON objects

JSON objects may contain additional fields not described below. Systems that do not recognize such additional fields should ignore them. Specifically, the endpoints defined in the Contest API contains file references. These files are contained in file packages in this standard and are thus not contained in the corresponding JSON objects, but a system may keep those file reference fields in JSON exported into a contest archive.

JSON types

The following JSON types are used.

Contest object

Differences from Contest API

• The countdown_pause_time is not included. It is allowed but the information should be ignored.
• The banner and logo elements are not included. They are allowed but the information may be ignored. These files are instead found as banner[.<size>].<format> and logo[.<size>].<format> in the contest directory.

Examples

{
   "id": "wf2014",
   "name": "2014 ICPC World Finals",
   "formal_name": "38th Annual World Finals of the ACM International Collegiate Programming Contest",
   "start_time": "2014-06-25T10:00:00+01",
   "duration": "5:00:00",
   "scoreboard_freeze_duration": "1:00:00",
   "penalty_time": 20,
}

Judgement type object

Differences from Contest API

None.

Examples

{
   "id": "AC",
   "name": "Accepted",
   "penalty": false,
   "solved": true
}

Language object

Differences from Contest API

None.

Examples

{
  "id": "cpp",
  "name": "C++",
  "compiler": {
    "command": "gcc",
    "args": "-O2 -Wall -o a.out -static {files}",
    "version": "gcc (Ubuntu 8.3.0-6ubuntu1) 8.3.0"
  }
}

{
  "id": "java",
  "name": "Java",
  "compiler": {
    "command": "javac",
    "args": "-O {files}",
    "version": "javac 11.0.4",
    "version-command": "javac --version"
  },
  "runner": {
    "command": "java",
    "version": "openjdk version \"11.0.4\" 2019-07-16"
  }
}

Command object

Examples

{
  "command": "gcc",
  "args": "-O2 -Wall -o a.out -static {files}",
  "version": "gcc (Ubuntu 8.3.0-6ubuntu1) 8.3.0"
}

{
  "command": "javac",
  "args": "-O {files}",
  "version": "javac 11.0.4",
  "version-command": "javac --version"
}

{
  "command": "java",
  "version": "openjdk version \"11.0.4\" 2019-07-16"
}

Problem object

Differences from Contest API

• The time_limit element is required to be a number that is an integer multiple of 0.001 in the Contest API.

Examples

{
  "id": "asteroids",
  "uuid": "cb1c4b77-b203-4943-a13f-9b89dec1ac11",
  "label": "A",
  "name": "Asteroid Rangers",
  "ordinal": 1,
  "rgb":"#00f",
  "color": "blue",
  "time_limit": 2,
  "test_data_count": 10
}

Group object

Differences from Contest API

None.

Examples

{
  "id": "asia",
  "icpc_id": "7593",
  "name": "Asia"
}

{
  "id": "42425",
  "name": "Division 2",
  "type": "division"
}

{
  "id": "ziqkpexycy",
  "name": "Sponsors",
  "type": "sponsors",
  "hidden": true
}

Organization object

Differences from Contest API

• The logo element is not included. It is allowed but the information may be ignored. These files are instead found as logo[.<size>].<format> in the in the organizations/<organization-ID> directory.

Examples

{
  "id": "kth.se",
  "icpc_ic": "INST-1039",
  "name": "KTH Royal Institute of Technology",
  "country":"SWE",
  "url": "http://www.kth.se/",
  "location": {
    "latitude": "59.347222",
    "longitude": "18.072778"
  }
 }

{
  "id": "sjtu.edu.cn",
  "icpc_ic": "INST-1663",
  "name": "Shanghai Jiao Tong U.",
  "formal_name": "Shanghai Jiao Tong University",
  "country":"CHN",
  "url": "http://en.sjtu.edu.cn/",
  "twitter_hashtag": "#SJTU",
  "location": {
    "latitude": "31.200833",
    "longitude": "121.429722"
  }
}

Location object

Examples

{
  "latitude": "59.347222",
  "longitude": "18.072778"
}

Team object

Differences from Contest API

• The photo, video, backup, key_log, tool_data, desktop, and webcam, audio elements are not included. They are allowed but the information may be ignored. These files are instead found in the same directory as the JSON file.

Examples

{
  "id": "11",
  "icpc_id": "201433",
  "name": "Shanghai Tigers",
  "organization_id": "sjtu.edu.cn",
  "group_ids": [
    "asia",
    "asia-east"
  ],
  "location": {
    "x": 10.25,
    "y": 2.4,
    "rotation": 90
  }
}

Position object

Examples

{
  "x": 10.25,
  "y": 2.4,
  "rotation": 90
}

Team member object

Differences from Contest API

• The photo element is not included. It is allowed but the information may be ignored. These files are instead found as photo[.<size>].<format> in the team-members/<team-member-ID> directory.

Examples

{
  "id": "john-smith",
  "icpc_id": "32442",
  "team_id": "43",
  "name": "John Smith",
  "email": "john.smith@kmail.com",
  "sex": "male",
  "role": "contestant"
}

 {
  "id":"osten-umlautsen",
  "team_id": "43",
  "name": "Östen Ümlautsen",
  "sex": null,
  "role": "coach"
}

Submission object

Differences from Contest API

• The files and reaction elements are not included. They are allowed but the information may be ignored. These files are instead found in the submissions/<submission-ID> directory.

Examples

{
  "id": "187",
  "team_id": "11",
  "problem_id": "asteroids",
  "language_id": "java",
  "time": "2014-06-25T11:22:05.034+01",
  "contest_time": "1:22:05.034",
  "entry_point": "Main"
}

Judgement object

Differences from Contest API

• The max_run_time element is required to be a number that is an integer multiple of 0.001 in the Contest API.

Examples

{
  "id": "189549",
  "submission_id": "wf2017-32163123xz3132yy",
  "judgement_type_id": "WA",
  "start_time": "2014-06-25T11:22:48.427+01",
  "start_contest_time": "1:22:48.427",
  "end_time": "2014-06-25T11:23:32.481+01",
  "end_contest_time": "1:23:32.481",
  "max_run_time": "2.23"
}

Run object

Differences from Contest API

• The run_time element is required to be a number that is an integer multiple of 0.001 in the Contest API.

Examples

{
  "id": "1312",
  "judgement_id": "189549",
  "ordinal": 28,
  "judgement_type_id": "AC",
  "time":"2014-06-25T11:22:42.420+01",
  "contest_time": "1:22:42.420",
  "run_time": "0.76"
}

Clarification object

Differences from Contest API

None.

Examples

{
  "id": "wf2017-1",
  "from_team_id": null,
  "to_team_id": null,
  "reply_to_id": null,
  "problem_id": null,
  "text": "Do not touch anything before the contest starts!",
  "time": "2014-06-25T11:59:27.543+01",
  "contest_time": "-0:15:32.457"
}

Event feed object

Differences from Contest API

No difference from old event feed model. Several differences from new webhook based model.

Examples

{
  "type": "submissions",
  "id": "593",
  "op": "create",
  "data": {
    "id": "187",
    "team_id": "11",
    "problem_id": "asteroids",
    "language_id": "java",
    "time": "2014-06-25T11:22:05.034+01",
    "contest_time": "1:22:05.034",
    "entry_point": "Main",
    "files": [{
        "href": "contests/wf14/submissions/187/files",
        "mime": "application/zip"
      }]
  }
}

Award object

Differences from Contest API

None.

Examples

{
  "id": "gold-medal",
  "citation": "Gold medal winner",
  "team_ids": ["54", "23", "1", "45"]
}

Scoreboard object

Exactly as defined in the Contest API

Differences from Contest API

None.

Examples

{
  "event_id": "xy1234",
  "time": "2014-06-25T14:13:07.832+01",
  "contest_time": "4:13:07.832",
  "state": {
    "started": "2014-06-25T10:00:00+01",
    "ended": null,
    "frozen": "2014-06-25T14:00:00+01",
    "thawed": null,
    "finalized": null,
    "end_of_updates": null
  },
  "rows": [{
    "rank": 1,
    "team_id": "123",
    "score": {"num_solved":3,"total_time":340},
    "problems": [
      {"problem_id":"1","num_judged":3,"num_pending":1,"solved":false},
      {"problem_id":"2","num_judged":1,"num_pending":0,"solved":true,"time":20},
      {"problem_id":"3","num_judged":2,"num_pending":0,"solved":true,"time":55},
      {"problem_id":"4","num_judged":0,"num_pending":0,"solved":false},
      {"problem_id":"5","num_judged":3,"num_pending":0,"solved":true,"time":205}
    ]
  }]
}

Binary files

Binary files related to certain object types are stored in a single parent directory with the same name as the object type and subdirectories with the same ID as en element of that object type. The JSON file with the same base name as the parent directory is the parent JSON file of the files. The name of the subdirectories must match an ID in the parent JSON file.

If there are no files for some organization (i.e. if a directory would be empty) it should be omitted.

The naming scheme used for all files is <basename>.[.<specifier>].<extension>. If there are multiple files with any given basename in a single directory, a specifier must be used for all except at most one.

For files that are referred to in the Contest API, the file extension for each file reference should match the mime type in the file reference object using the following mapping:

Problem package

Problems packages are stored in a single directory, or alternatively in a ZIP compressed archive using the file extension .kpp, according to the Kattis Problem Package Format specification.

Problem packages may be left out if (and only if) config/problems.json contains uuid for those problems. This assumes that the problems are stored elsewhere and can be found by matching by the uuid, and this should be checked when verifying a contest archive.

Contest files

The contest directory contain all binary files related to a single contest in it's parent JSON file.

The following files could be in the contest directory:

Organization files

The organization directories contain all binary files related to a single organization in it's parent JSON file.

The following files could be in the organization directories:

Team files

The team directories contain all binary files related to a single team in it's parent JSON file.

The following files could be in the team directories:

Team member files

The team member directories contain all binary files related to a single team member in it's parent JSON file.

The following files could be in the team member directories:

Submission files

The submission directories contain all binary files related to a single submission in it's parent JSON file.

The following files could be in the submission directories: