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:
  ...

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`, `expression`, or `member_of`)	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`, `expression`, or `member_of`)	A regular expression that valid values must match. See https://github.com/google/re2/wiki/Syntax for more details about the used regexp syntax.	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`
member_of (optional, use either `values`, `expression`, or `member_of`)	A URL of a members list in the call history file format.	The BCC members list: `member_of: https://www.bavarian-contest-club.de/data/bcc-members.txt`

Predefined Properties

Name	Description
age	The operator's age.
callsign	Any callsign; may be used in a memorial contest for as exchange.
class	The operator class (depends on the contest, may contain only letters).
continent	The continent; may be used as an exchange, e.g. in the LABRE-DX contest.
cq_zone	The CQ zone.
distance	*This property requires the locator* property.** The distance in kilometers.
dxcc_prefix	The DXCC primary prefix.
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).
itu_zone	The ITU zone.
locator	The maidenhead locator; may be used as exchange in a VHF/UHF contest.
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).
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

The exchange section defines the data that is exchanged in a contest QSO. It is possible to define multiple sets of exchange for participants that meet different conditions.

To find the best matching definition for a QSO, each definition is given a weight, depending on how many of its defined conditions are met by the QSO. The exchange definition with the highest weight wins.

Name	Purpose/Values	Example
my_continent (optional)	Limit this exchange definition to QSOs where my continent matches the given value(s). Possible values: `af`, `an`, `as`, `eu`, `na`, `sa`.	`my_continent: [af, an, as, na, oc, sa]` matches continents but EU
my_country (optional)	Limit this exchange definition to QSOs where my country matches the given value(s). Possible values are all primary DXCC prefixes.	`my_country: [not, k, ve]` matches all countries except USA and Canada
their_continent (optional)	Limit this exchange definition to QSOs where their continent matches the given value(s). Possible values: `af`, `an`, `as`, `eu`, `na`, `sa`.	`their_continent: [eu]` matches the continent EU
their_country (optional)	Limit this exchange definition to QSOs where my country matches the given value(s). Possible values are all primary DXCC prefixes.	`their_country: [k, ve]` matches USA and Canada
their_working_condition (optional)	Limit this exchange definition to QSOs where *their working condition` matches the given value(s).	`their_working_condition: [mm]` matches maritime mobile stations
additional_weight (optional)	Gives this exchange definition an additional weight to enforce precedence of this definition.	`additional_weight: 100`
fields	A list of lists of property names that define the data that is exchanged in a contest QSO.	`fields:` `- [rst]` `- [serial]` `- [member_number,nm]`

The lists defining countries, continents, or working conditions may have the value not as their first element. In this case the list is inverted.

Example:

their_country: [k, ve] matches QSOs where the opposite station is from USA or Canada.
their_country: [not, k, ve] matches QSOs where the opposite station is not from USA or Canada.

Example: exchange definitions for the DARC XMAS contest

German stations send their report and either nm or their DARC DOK. Foreign stations send their report and their serial number.

exchange:
- their_country: [dl]
  fields:
  - [rst]
  - [nm, wag_dok]
- fields:
  - [rst]
  - [serial]

Scoring

The scoring section describes all the set of rules for calculating the contest score. It is divided in the subsections:

Name	Purpose/Values	Example
qsos	Defines the calculation rules for QSO points.	see below
qso_band_rule	Defines if the same station may be worked only once, once per band, or once per band and mode. Possible values: `once`, `once_per_band`, `once_per_band_and_mode`	`qso_band_rule: once_per_band`
multis	Defines the calculation rules for the multipliers.	see below
multi_operation	Defines if the number of multis is multiplied with the QSO points (default) or added to the QSO points to calculate the overall contest score. Possible values: `multiply`, `add`	`multi_operation: add`

Scoring Rules

The QSO points and multipliers are calculated based on a set of scoring rules. Each rule defines a value and a set of constraints, under which the value is applied.

When evaluating a specific QSO, each matching rule is assigned a weight, depending on how specific its constraints are. The more constraints a rule defines, the higher its weight is. The rule with the highest weight wins.

Name	Purpose/Values	Example
my_continent	Restricts this rule to QSOs where my continent matches the given value(s).	`my_continent: [eu]`
my_country	Restricts this rule to QSOs where my country matches the given value(s).	`my_country: [dl]`
my_prefix	Restricts this rule to QSOs where my prefix matches the given value(s).	`my_prefix: [kh6, kl7, cy9, cy0]`
my_working_condition	Restricts this rule to QSOs where my working condition matches the given value(s).	`my_working_condition: [not, p]`
their_continent	Restricts this rule to QSOs where their continent matches the given value(s).	`their_continent: [not, eu]`
their_country	Restricts this rule to QSOs where their country matches the given value(s).	`their_country: [k, ve]`
their_prefix	Restricts this rule to QSOs where their prefix matches the given value(s).	`their_prefix: [dl1, dj1, dk1, dm1]`
their_working_condition	Restricts this rule to QSOs with their working condition matchinge the given value(s).	`their_working_condition: [mm]`
bands	Restricts this rule to QSOs on certain bands.	`bands: [160m, 80m]`
property_constraints	Defines more specific contraints for a certain property.	see below
additional_weight	Gives this rule additional weight to give it precedence.	`additional_weight: 100`
value	The value of QSOs matching this rule (either QSO points or multipliers).	`value: 5`
value_of_property	The value of the QSO is determined by the given derived property. The actual value must be numerical.	`value_of_property: distance`

The following fields are only used for rules regarding multipliers:

Name	Purpose/Values	Example
property	The QSO's property that is used as multiplier.	`property: dxcc_entity`
except	A list of values that are not counted as multiplier.	`except: [ha]` excludes the DXCC entity `ha` from the possible multipliers.
band_rule	Defines if a multiplier counts once, once per band, or once per band and mode. Possible values: `once`, `once_per_band`, `once_per_band_and_mode`	`band_rule: once`

Property Constraints

Name	Purpose/Values	Example
name	The property's name. This could be either a predefined property, or a user defined one.	`name: class`
min (optional)	The minimum value (for numerical properties).	`min: 26`
max (optional)	The maximum value (for numerical properties).	`max: 16`
my_value (optional)	Matches QSOs where my value of this property is equal to the given value.	`my_value: qro`
their_value (optional)	Matches QSOs where their value of this property is equal to the given value.	`their_value: qrp`
their_value_empty (optional)	Matches QSOs where their value of this property is empty. Possible values: `true`, `false`
their_value_not_empty (optional)	Matches QSOs where their value of this property is empty. Possible values: `true`, `false`	see below
same (optional)	Matches QSOs where my value and their value of this property are the same.	see below
other (optional)	Matches QSOs where my_value and their value of this property are different.	see below

Examples

They have a different ITU zone:

scoring:
  qsos:
  - property_constraints:
    - name: itu_zone
      their_value_not_empty: true
      other: true
    value: 2

They have the same ITU zone:

scoring:
  qsos:
  - property_constraints:
    - name: itu_zone
      their_value_not_empty: true
      same: true
    value: 1

Examples

The examples section contains several list of example QSOs that are used to verify that the defined rules work as expected. Each example is divided into three subsections:

the setup defines the overall working conditions (bands, modes, my settings)
qsos with their individual score is used to verify the score calculation
the overall score score is also used to verify the score calculation

In both the setup subsection and also in the individual example QSOs, only those fields relevant for the score calculation should be filled with data, to keep the examples comprehensible.

Currently, only the score calculation is checked. In the future, also other rules, for example regarding the operation time or band changes, may be checked.

Example Setup

Name	Purpose/Values	Example
my_call (optional)	The value for my call.	`my_call: dl1abc`
my_contient (optional)	The value for my continent. Possible values: `af`, `as`, `eu`, `na`, `sa`, `oc`	`my_continent: eu`
my_country (optional)	The primary DXCC prefix for my country.	`my_country: dl`
grid_locator (optional)	The maidenhead grid locator for this station (currently not used for score calculation).	`grid_locator: jn59aa`
operators (optional)	The list of operator callsigns (currently not used for score calculation).	`operators: [dl1abc,dl2abc]
operator_mode (optional)	The operator mode (currently not used for score calculation). Possible values: `single`, `multi`	`operator_mode: multi`
overlay (optional)	The rules overlay (currently not used for score calculation). Possible values: `classic`, `tb_wires`, `rookie`, `youth`	`overlay: classic`
power (optional)	The output power (currently not used for score calculation). Possible values: `high`, `low`, `qrp`	`power: qrp`
bands (optional)	The bands used in the contest. Possible values: `all`, 160m`, 80m`, 40m`, 20m`, 15m`, 10m`	`bands: [all]` uses all bands as defined in the contest rules
modes (optional)	The modes used in the contest. Possible values: `all`, cw`, ssb`, fm`, rtty`, digital`	`modes: [all]` uses all the modes defined in the contest rules, for example ssb and cw
my_exchange	The values for all parts of my exchange as a set of properties.	`my_exchange:` `rst: 599` `wag_dok: z99`

Example QSOs

Name	Purpose/Values	Example
their_call (optional)	The callsign of the opposite station.	`their_call: dl1abc`
their_continent (optional)	The continent of the opposite station.	`their_continent: eu`
their_country (optional)	The primary DXCC prefix of the opposite station's country.	`their_country: dl`
time (optional)	The time of the QSO (currently not used for score calculation).
band (optional)	The band. Possible values: `160m`, `80m`, `40m`, `20m`, `15m`, `10m`	`band: 10m`
mode (optional)	The mode. Possible values: `cw`, `ssb`, `fm`, `rtty`, `digital`	`mode: cw`
their_exchange	Their exchange as a list of strings.	`their_exchange: [599, z99]´
score	The QSO's individual score.	see below

Country and continent information must be set explicitely. Those values are not automatically derived from the callsign.

Their exchange is evaluated using the defined exchange configuration. This means, also the exchange parsing and the definition of user defined properties can be checked.

Example QSO Score

Name	Purpose/Values	Example
points	The points for this QSO. Must also be filled out, if this is a duplicate QSO.	`points: 3`
multis	The multipliers for this QSO.	`multis: 1`
duplicate (optional)	Indicates if this is a duplicate QSO. Possible values: `true`, `false`	`duplicate: false`

Example Score

Name	Purpose/Values	Example
qsos	The number of QSOs.	`qsos: 7`
points	The final number of QSO points (without the duplicate QSOs).	`points: 35`
multis	The final number of multipliers.	`multis: 3`
total	The total score.	`total: 105`

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)
changes_per_hour: int (optional)
include_mode_changes: true|false (optional)

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`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!