Implement ACD

A document, end to end

The five content blocks of a real definition, colour-coded. Four of them are flat and declarative; scoring is the hard one, by design and not by accident.

identity:
    uuid:            9f2b6d41-7c33-4a8e-b5d0-1e8a7c4f2b90
    slug:            cq-ww-ssb
    name:            "CQ World Wide DX Contest, SSB"
    sponsor:         "CQ Magazine"
    cabrillo_name:   CQ-WW-SSB
    adif_contest_id: CQ-WW-SSB
    rules_url:       https://cqww.com/rules.htm

  schedule:
    recurrence:      "last full weekend of October"
    window:
      start:         { weekday: saturday, time: "00:00" }
      duration:      PT48H

  operating:
    bands:           [160m, 80m, 40m, 20m, 15m, 10m]
    modes:           [SSB]

  exchange:
    - send:
        - { name: rs,   type: rst }
        - { name: zone, type: enum, vocabulary: cq-zones }

  scoring:
    score_type:      claimed
    reference_data:
      - { name: cty,            version: cty-3501 }
      - { name: cqww-countries, version: cty-3501 }
    derive:
      worked.cont:    "resolve_continent(worked.call, cty)"
      worked.country: "resolve_country(worked.call, cqww-countries)"
    dupe:            [worked.call, band, mode]
    qso_points:
      - when: worked.country == me.country
        then: 0
      - when: worked.cont != me.cont
        then: 3
      - when: me.cont == 'NA'
        then: 2
      - else: 1
    multipliers:
      - { source: received.zone,  scope: per_band }
      - { source: worked.country, scope: per_band }
    formula:         sum(qso_points) * count(multipliers)

What is actually specified

Every one of these lists is closed. An unknown value is a validation error, not an extension point — that is what stops ACD from drifting into one logging program's export format.

7 Element types

rst, serial, enum, number, string, callsign, locator. length is the only shape specification.

14 Constraint types

A catalogue, each type with fixed fields and a fixed enforceability level.

8 Category dimensions

Grounded in what the entrant declares, not in a log format.

3 Point forms

A number, a table by band or mode group, and one declarative transform.

2 Grammars

Conditions are purely boolean. formula does arithmetic and knows no paths.

9 Primitives

Each with a versioned contract and at least one test vector per rule.

Adding an element type, a catalogue entry or a language capability is a version jump, not a free-form field in the document.

Three gates before publish

Nothing reaches published without clearing all three. Two of them are incomplete, and saying so is the point.

1. 01

   Editorial

   Is the rule source cited? Is an interpretation marked as an interpretation? A human decides this; no machine can.

2. 02

   Static

   Is the document internally consistent, without executing it? The JSON Schema decides everything visible in a single object; the rest needs the linter below.

3. 03

   Dynamic

   Does a reference engine reproduce the document's own hand-calculated conformance cases? The engine is a separate project and is not built yet.

The document, field by field

Nine top-level keys are required, seven are optional. Four of the content blocks are flat and declarative. Scoring is the hard one, by design.

The seven element types

Closed list. An exchange element and a profile field draw from the same set, so a value the entrant sends and a value they declare are described identically.

length is the only shape specification there is. No pattern: a regular expression in an element field is the same foreign code in someone else's scorer as one in a when. And a received value is never rewritten — whoever needs a transformed value names it with derive and reads it back from qso.*

Category dimensions

A dimension says one thing only: who you are ranked against. It never says what you are allowed to do — that lives in constraints, always, even when the same fact is also a dimension.

The list is closed because six hand-written contests needed exactly these, not because a committee maintains a header list. The Cabrillo column is the concrete form of the entrant's declaration for five of the six — but Cabrillo's own vocabularies change, so an ACD value is informed by it and not bound to it. ACD writes values lower case, Cabrillo upper case; the mapping is mechanical.

The constraint catalogue

Fourteen types, closed, each with its own fields and a fixed enforceability level. This is where a logger finds out what an entry may actually do, instead of guessing it from the category name.

checkable means a scorer can decide it from the log alone. declarable means the entrant asserts it and only data outside the log could disprove it. advisory means prose: display it, never apply it. declarable is by far the largest group, and that is an honest finding rather than a gap — most contest rules are simply not decidable from a log. Permission fields carry three values, not two: permitted, forbidden and restricted, the last one only ever with a note.

What the schema cannot check

The JSON Schema decides everything visible in a single object. Everything that weighs two parts of a document against each other has no expression in JSON Schema at all, and needs a linter that is not written yet. The gap is listed here rather than discovered later.

Twenty of these are code that does not exist. They belong with the reference engine, which is not built either. Until then the schema catches the shape errors, a human catches the rest, and this list says exactly where the boundary runs.

Versioning and status

The reference is a contract. These rules are what make it one.

Glossary

The domain is unfamiliar to most developers. These are the terms the spec assumes.

Integration examples

Example client code in several languages ships alongside the schema. not yet available