Contest Archive Format

From ICPC-Contest Control Standard

This page describes a draft archivel format for a contest. It is developed in parallel with the Contest API. It might very well end up being very similar to the CDP which has been suggested to use for this, but which have a slightly different purpose...

Introduction

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 based on the Contest API structure, and a dump of the output from that API is one way to store the data. That said, the archive format allows for any format whose documentation has been registered with the ICPC. The sections below lists all currently known (and thus accepted) formats.

Structure

The Contest Archive consists of a single directory (possibly ZIP compressed) with a metadata file (archive.yaml) and at most a single entry for each of the types of data (config, problems, registration, activity, results, events). An entry is either a directory with the same name as the type of data, or a file with same base name as the type of data and any file extension.

Metadata

Archive metadata is stored in a YAML file called archive.yaml with the following keys:

Key Description
created-by Name of system creating this archive
archive ID of format used for content types not listed in archive.yaml
config ID of format used for config
problems ID of format used for problems
registration ID of format used for registration
activity ID of format used for activity
results ID of format used for results
events ID of format used for events

Only created-by is always required, but if any of content type is not listed then archive must be specified.

Example

# Contest Archive
---
created-by: Kattis
archive:    contest-api
problems:   kattis
events:     missing

Config

Configuration data for the contest.

The following formats may be used:

ID Description Specification
contest-api Contest API dump https://clics.ecs.baylor.edu/index.php/Contest_Archive_Format#Config_2

Problems

Problems used at the contest.

The following formats may be used:

ID Description Specification
kattis Kattis problem package format http://www.problemarchive.org/
icpc ICPC problem package format (subset of the Kattis format) https://clics.ecs.baylor.edu/index.php/Problem_format

Registration

Registration data for the contest.

The following formats may be used:

ID Description Specification
contest-api Contest API dump https://clics.ecs.baylor.edu/index.php/Contest_Archive_Format#Registration_2

Activity

Activity in the form of submissions, judgements, runs and clarifications from the contest.

The following formats may be used:

ID Description Specification
contest-api Contest API dump https://clics.ecs.baylor.edu/index.php/Contest_Archive_Format#Activity_2

Results

Final results from the contest.

The following formats may be used:

ID Description Specification
contest-api Contest API dump https://clics.ecs.baylor.edu/index.php/Contest_Archive_Format#Results_2

Events

List of events from the contest.

The following formats may be used:

ID Description Specification
contest-api Contest API dump https://clics.ecs.baylor.edu/index.php/Contest_Archive_Format#Events_2
missing No events data

Contest API archive formats

NB!: This section should not be in this document, and is only included here while WIP. It should either be its own document, or be added to the Contest API document. Every subsection defines the on disk format contest-api for a type of data.

General principle

Endpoints are stored in a single <endpoint>.json file containing the full list of objects. This file is identical to the API call to /<endpoint>. If there are file references in the JSON file these are stored in a subfolder per object, using the endpoint name and object ID as the folder names.

<endpoint>.json
<endpoint>/<id>/<other files>

Config

A directory, config, containing:

  • a JSON file (contest.json) for the /contests/<id> endpoint
  • a JSON file (judgement-types.json) for the /contests/<id>/judgement-types endpoint
  • a JSON file (languages.json) for the /contests/<id>/languages endpoint
  • system.yaml defined in the CCSR.
  • the contest banner(s), from the banner element of /contests/<id>, if available.
  • the contest logo(s), from the logo element of /contests/<id>, if available.

File listing

config/contest.json
config/judgement-types.json
config/languages.json
config/system.yaml
config/banner.png
config/logo.png

Registration

A directory, registration, containing:

  • a JSON file (groups.json) for the /groups endpoint
  • a directory for organizations containing:
    • a JSON file (organizations.json) for the /organizatons endpoint
    • a directory for each organisation using the organisation ID as directory name, containing:
      • a file for each endpoint available under /organizatons/<id>
  • a directory for teams containing:
    • a JSON file (teams.json) for the /teams endpoint
    • a directory for each team using the team ID as directory name, containing:
      • a file for each endpoint available under /teams/<id>
  • a directory for team-members containing:
    • a JSON file (team-members.json) for the /team-members endpoint
    • a directory for each team member using the team member ID as directory name, containing:
      • a file for each endpoint available under /team-members/<id>

File listing

registration/groups.json
registration/organizations.json
registration/organizations/<id>/logo.png
registration/organizations/<id>/logo.160px.png
registration/organizations/<id>/logo.56px.png
registration/teams.json
registration/teams/<id>/photo.{png,jpg}
registration/teams/<id>/backup.zip
registration/team-members.json
registration/team-members/<id>/photo.{png,jpg}

Activity

A directory, activity, containing:

  • a directory for submissions containing:
    • a JSON file (submissions.json) for the /submissions endpoint
    • a directory for each submission using the submission ID as directory name, containing:
      • a file for each endpoint available under /submissions/<id>
  • a directory for judgements containing:
    • a JSON file (primary.json) for the /judgements endpoint for the primary system
    • a JSON file (shadow{1,2,...}.json) for the /judgements endpoint for a shadow system if any (use number in case of multiple shadows)
  • a directory for runs containing:
    • a JSON file (primary.json) for the /runs endpoint on the primary system
    • a JSON file (shadow{1,2,...}.json) for the /runs endpoint on a shadow system, if available (use numbering in case of multiple shadows)
  • a JSON file, clarifications.json for the /clarifications endpoint


File listing

activity/submissions.json
activity/submissions/<id>/files.zip
activity/submissions/<id>/reaction.*
activity/judgements/primary.json
activity/judgements/shadow.json
activity/runs/primary.json
activity/runs/shadow.json
activity/clarifications.json

Results

A directory, results, containing:

  • A JSON file, awards.json for the /awards endpoint
  • A JSON file, scoreboard.json for the /scoreboard endpoint

File listing

results/awards.json
results/scoreboard.json

Events

A directory, events, containing:

  • a JSON file (primary.json) for the /event-feed endpoint on the primary system
  • a JSON file (shadow{1,2,...}.json) for the /event-feed endpoint on a shadow system, if available (use numbering in case of multiple shadows)
  • a JSON file (*.json) for the /event-feed endpoint on any other system producing events, if available (may not be named "primary" or "shadow*")

File listing

events/primary.json
events/shadow.json
events/cds.json