Rules File Format

The basic file format for rule files is YAML. The following describes the specific data structures in use.

Top Level Elements

Element	Purpose	Example
name	The contest's human-readable name.	name: CQ World Wide DX Contest CW
identifier	The contest's Cabrillo identifier. You can find a list of identifiers for example in WA7BNM's contest calendar.	identifier: CQ-WW-CW
official_rules	The URL of the contest's official rules description.	official_rules: https://www.cqww.com/rules.htm
upload_url	The URL for uploading the final contest log.	upload_url: https://cqww.com/logcheck/
upload_format	The accepted log file format, currently only cabrillo is supported.	upload_format: cabrillo
duration (optional)	The contest's duration, using Go's string representation for durations.	duration: 48h
duration-constraints (optional, beta)	The constraints regarding operation time.	see below
breaks (optional, beta)	The constraints regarding required breaks.	see below
categories (optional)	The contest's competition categories.	see below
overlays (optional)	An overlay defines an additional set of restrictions. Common overlays are classic, tb_wires, rookie, or youth, but you may use any arbitrary name in this enumeration. The selected overlay is usually put into Cabrillo's CATEGORY-OVERLAY field.	overlays: [classic, tb_wires, rookie, youth]
modes (optional)	The allowed operation modes.	modes: [cw, ssb]
bands (optional)	The allowed bands for contest operation.	bands: [160m, 80m, 40m, 20m, 15m, 10m]
band_change_rules (optional, beta)	The constraints regarding band changes.	see below
properties (optional)	The description of contest-specific properties, which are used as exchanged information, or are relevant for the score calculation.	see below
exchange	The description of the exchanged information.	see below
scoring	The rules for calculating the final score.	see below
examples (optional)	The example QSO data which may be used to validate the rules.	see below

Optional fields may be omitted or left blank. The data structures used in fields that are marked as beta are still under development and subject to change in the future.

Example: Basic Structure of a Rule File

identifier: CQ-WW-CW
name: CQ World Wide DX Contest CW
official_rules: https://www.cqww.com/rules.htm
upload_url: https://cqww.com/logcheck/
upload_format: cabrillo
duration: 48h
duration-constraints:
  ...
breaks:
  ...
categories:
  ...
overlays: [tb_wires, rookie, classic, youth]
modes: [cw]
bands: [160m, 80m, 40m, 20m, 15m, 10m]
exchange:
  ...
scoring:
  ...
examples:
  ...

Categories

Name	Purpose/Values	Example
name	The category's human-readable name.	name: "SO-AB High"
operator_mode (optional)	single: single operator multi: multi-operator	operator_mode: "single"
tx (optional)	one: one transmitter two: two transmitters multi: multiple transmitters at the same location distributed: multiple transmitters at different locations (see CQ WPX)	tx: "one"
power (optional)	high: high power class low: low power class qrp: qrp power class The exact criteria depend on the contest.	power: "high"
band_count (optional, requires bands)	The number of allowed bands. all: all defined bands are allowed <number>: only <number> of the allowed bands may be used single: only a single band may be used	band_count: 3 bands: [160m, 80m, 40m, 20m, 15m, 10m]
bands (optional)	Defines all bands that may be used in the category. Currently only shortwave contest bands are supported: all, 160m, 80m, 40m, 20m, 15m, 10m all is a placeholder for all shortwave contest bands.	bands: [all]
modes	Defines the modes that may be used in the category. Possible values: all, cw, ssb, fm, rtty, digital all is a placeholder for all modes.	modes: [cw, ssb]
assisted (optional)	Indicates if any assisting tools (clusters, cw skimmer, etc.) are allowed in the category. The exact details depend on the contest	assisted: true
overlay (optional)	The overlay for this category. The available overlays are defined at the top level.	overlay: youth
score_mode (optional)	Defines how the overall score is calculated: strict: only the number of bands defined in band_count may be used. If more bands are used, the claimed score is zero. best: Any band may be used, best bands according to band_count are counted for the overall score. (see YOTA Contest) strict is the default and may be omitted.	score_mode: best
duration (optional)	The maximum activity time in this category.	duration: 6h

Example Categories

Single Operator, All Band, High Power from CQ WPX:

categories:
- name SO-AB High
  operator_mode: single
  power: hight
  band_count: all

Single Operator, Three Bands, Mixed Mode, "Open" from YOTA Contest

bands: [80m, 40m, 20m, 15m, 10m]
modes: [cw, ssb]
categories:
- name: SO-3B Mixed (open)
  operator_mode: single
  band_count: 3
  modes: [all]
  score_mode: best

Single Operator, All Bands, Mixed Mode, "YOTA" from YOTA Contest

bands: [80m, 40m, 20m, 15m, 10m]
modes: [cw, ssb]
- name: SO-AB Mixed (YOTA)
  operator_mode: single
  band_count: all
  modes: [all]
  overlay: youth

Single Operator, All Bands, Mixed Mode, "YOTA12H" from HA-DX Contest

categories
- name: YOUTH12H
  operator_mode: single
  overlay: youth

Properties

A property is one piece of data that is associated with one QSO and which has certain semantics. Properties are either directly entered as part of the QSO, or derived from other properties. They are used to associate semantics to the QSO exchange fields (see Exchange) and to describe the conditions that are used to calculate the score of a given QSO (see Scoring Rules).

Conval has a set of predefined common properties, but must contests define specific data that is used as QSO exchange. The specific semantics of this data can be described using the properties data structure.

Name	Purpose/Values	Example
name	The property's unique name.	name: example_property
label (optional)	A short, human-readable label for the property.	label: ex
values (optional, use either values or expression)	A list of valid values.	Hungarian Counties: values: [BN, BA, BE, BO, CS, FE, GY, HB, HE, SZ, KO, NG, PE, SO, SA, TO, VA, VE, ZA, BP]
expression (optional, use either values or expression)	A regular expression that valid values must match.	The DARC DOK: expression: "\\d*[A-Z][A-Z0-9ÄÖÜ-]*"
source (optional)	The name of the property that this one is derived from. The value of this property is usually derived by applying a regular expression on the source property. If the expression contains a capture group, the content of this capture group is used as value for the property. See the example below for more details about derived properties.	source: other_property

Predefined Properties

Name	Description
age	The operator's age.
callsign	Any callsign; maybe used in a memorial contest for as exchange.
class	The operator class (depends on the contest, may contain only letters).
cq_zone	The CQ zone.
dxcc_prefix	The DXCC primary prefix.
dxcc_zone	The DXCC zone.
empty	Use this property to mark an exchange field that may be omitted.
generic_number	Any number (may contain only digits).
generic_text	Any text (may contain letters and digits, but must begin with a letter).
member_number	A membership number.
name	The operator's name.
nm	"No Member", usually used in a club contest by non-members instead of the membership number.
power	The used power (actual value depends on the contest, may contain letters and digits).
itu_zone	The ITU zone.
rst	The report.
serial	The QSO's serial number.
state_province	The US state or Canadian province, used in ARRL contests (see also ARRL contest multipliers).
their_call	The other operator's callsign.
wae_entity	The WAE entity as defined here
working_condition	The working condition: am = aeronautical mobile m = mobile mm = maritime mobile p = portable
wpx_prefix	The prefix as used in the CQ WPX contests.
	DEPRECATED PROPERTIES
eu_region	eudx: EU region (deprecated)
pa_province	pacc: province (deprecated)
veron_entity	pacc: VERON entity (deprecated)

Example Derived Property

From the CQMM DX Contest:

properties:
- name: cqmm_exchange
  expression: "((AF)|(AS)|(EU)|(NA)|(OC)|(SA))[CMQY]?"
- name: cqmm_group
  source: cqmm_exchange
  expression: "[AENOS][ACFSU]([CMQY]?)"

The actual value of cqmm_group is taken from the expression's capture group, i.e. possible values are C, M, Q, or Y.

Exchange

• my_continent (optional)
• my_country (optional)
• their_continent (optional)
• their_country (optional)
• their_working_condition (optional)
• additional_weight
• fields: list of list of property names (optional)

Scoring

• qsos (optional)
• qso_band_rule: once|once_per_band|once_per_band_and_mode (optional)
• multis (optional)
• multi_operation: multiply|add (optional)

Scoring Rules

• my_continent (optional)
• my_country (optional)
• my_prefix (optional)
• my_working_condition (optional)
• their_continent (optional)
• their_country (optional)
• their_prefix (optional)
• their_working_condition (optional)
• bands: [all, 160m, 80m, 40m, 20m, 15m, 10m] (optional)
• property (optional)
• except: list of strings (optional)
• property_constraints (optional)
• band_rule: once|once_per_band|once_per_band_and_mode (optional)
• additional_weight (optional)
• value (optional)

Property Constraints

• name
• min (optional)
• max (optional)
• my_value (optional)
• their_value (optional)
• their_value_empty: true|false (optional)
• their_value_not_empty: true|false (optional)
• same: true|false (optional)
• other: true|false (optional)

Examples

• setup
• qsos
• score

Example Setup

• my_call (optional)
• my_contient: af|as|eu|na|sa|oc (optional)
• my_country (optional)
• grid_locator (optional)
• operators: list of strings (optional)
• operator_mode: single|multi (optional)
• overlay: classic|tb_wires|rookie|youth (optional)
• power: high|low|qrp (optional)
• bands: [all, 160m, 80m, 40m, 20m, 15m, 10m] (optional)
• modes: [all, cw, ssb, fm, rtty, digital] (optional)
• my_exchange: map[property]string

Example QSOs

• their_call (optional)
• their_continent (optional)
• their_country (optional)
• time (optional)
• band: 160m|80m|40m|20m|15m|10m (optional)
• mode: cw|ssb|fm|rtty|digital (optional)
• their_exchange: list of strings
• score

Example QSO Score

• points
• multis
• duplicate: true|false (optional)

Example Score

• qsos
• points
• multis
• total

Beta Sections

The data structures for the following sections are still under development and subject to change.

Duration Constraints and Breaks

• operator_mode: single|multi
• overlay: classic|tb_wires|rookie|youth
• duration
• constraint_mode: total_time|active_time

Band Change Rules

• operator_mode: single|multi (optional)
• overlay: classic|tb_wires|rookie|youth (optional)
• grace_period
• multiplier_exception: true|false (optional)