Condition language v1

A condition is a small JSON value that says what an agent is waiting for. CastHQ evaluates it against each change envelope on the target and fires when it becomes true. No code, no regular expressions, no JSON paths: every leaf names a field from a fixed list. Schema: /v1/condition.json.

Condition := Leaf | { "all": [Condition] } | { "any": [Condition] } | { "not": Condition }

Leaf :=
  | { "change": Kind | [Kind], "semantic"?: [Semantic], "origin"?: [Origin] }
  | { "change": "schedule", "moved_by": { "gt" | "gte": Duration }, "direction"?: "later" | "earlier" | "either" }
  | { "change": "dispute", "opened"?: boolean, "loser_origin"?: [Origin] }
  | { "status": { "becomes"?: Status, "from"?: Status, "in"?: [Status] } }
  | { "availability": { "becomes"?: Availability, "from"?: Availability, "in"?: [Availability] } }
  | { "lineup": { "includes": TopicUrn } }
  | { "state":  { "becomes"?: State, "in"?: [State] } }
  | { "fact": "schedule" | "status" | "location" | "availability" | "lineup",
      "confidence": { "becomes"?: Level, "becomes_at_least"?: Level, "at_least"?: Level, "drops_below"?: Level } }
  | { "fact": "schedule" | "status" | "location" | "availability" | "lineup",
      "sources": { "at_least": N } | { "becomes_at_least": N } }
  | { "precision": { "becomes_at_least": Precision } }
  | { "listed": { "becomes": boolean } }
  | { "time": { "anchor": "start" | "end" | "deadline" | "on_sale", "offset": Duration,
                "when_imprecise"?: "wait" | "earliest" | "latest", "tz"?: IanaZone } }
  | { "time": { "at": DateTime, "tz"?: IanaZone } }
  | { "dependency": { "at_risk"?: true, "parent_state"?: { "becomes": State } } }
  | { "variant": { <axis>: Term | Term[] } }
  | { "members":  ({ "all" | "any": Level } | { "count_at_least": N, "of": Level }), "where"?: { "variant": … } }
  | { "upstream": { "all" | "any": Level } | { "count_at_least": N, "of": Level } }

Level := status "in", availability "in", lineup "includes", state "in", confidence "at_least", precision "at_least",
         sources "at_least", and "all" / "any" / "not" of those

The top-level object may carry "v": 1. Unknown keys and values are refused with the path to the mistake.

Values

• Kinds: created, schedule, status, title, location, links, published, merged, dispute, phase, confidence, dependency (an edge added or removed, or the event put at_risk by something it depends on), availability (ticket availability or the on-sale time moved), lineup (who takes part moved), recurrence (a series' rule moved), and the reserved expectation and variant (a variant parent gained or lost a variant).
• Semantics (schedule moves): scheduled, moved_earlier, moved_later, narrowed, widened, undated; dispute changes: opened, resolved; dependency changes: added, removed, at_risk.
• Origins: producer, observed, admin.
• Statuses: announced, scheduled, live, completed, cancelled, postponed, delayed (held, timing unknown, expected to resume; not moved, not called off).
• Availability (tickets, as the sources say it): not_on_sale, on_sale, few_left, sold_out, waitlist, unavailable. A fact, not a status: a sold-out event still happens, and its status and state do not move. CastHQ records it and never sells or holds tickets.
• States: announced, date_expected, scheduled, date_confirmed, live, released, ended, overdue, delayed, postponed, cancelled (see lifecycle state).
• Levels, low to high: disputed < uncertain < likely < confirmed (see Confidence).
• Precisions, fine to coarse: datetime, day, month, quarter, half, season, year, window, tba.
• Time anchors: start and end of the event; deadline, a commitment's due time (its end; a timer firing reports it as end), refused on any other event; on_sale, when tickets go on sale (the event's on_sale_at), re-armed when a source moves it, event targets only.
• Durations: ISO 8601 weeks, days, hours, minutes and seconds (P3D, PT2H, P1DT12H). Years and months are refused: their length depends on the calendar. A time offset is signed (negative is before the anchor). A relative schedule ({"relative": {"to", "anchor", "offset", "duration"}} in a schedule claim) reads the same durations: its offset is signed, its optional duration (how long the dependent lasts, so its end moves with its start) is positive.

Limits

Evaluation

A condition is judged against one envelope at a time, and only against what the envelope carries: its kind, semantic, old / new, delta, provenance origin and the before / after snapshots stored on the change. Never against today's state, so replaying a condition over history answers "what would have fired at the time".

• Edge leaves (becomes, from, becomes_at_least, drops_below, change, moved_by, listed, precision, time) are true at the change that makes them so, comparing before with after. A change with no before (created) counts as everything becoming what after says.
• Level leaves (in, at_least) are true on every change while the state holds, read off after. Use them inside all to gate an edge.
• sources counts the independent sources that agree with a fact's shown value: distinct source domains, not claims. Ten scrapes of one site count once, a subdomain counts as its site, and a claim with no public link counts toward none. N is 1 to 64. at_least is a level, becomes_at_least an edge: it fires once when the count reaches N, and a further claim from a site already counted does not fire it again. It is for "three of five feeds agree", not a numeric confidence: the confidence levels stay the contract. Unknown on changes recorded before snapshots carried source counts.
• availability reads the snapshots' availability; fact: "availability" is its confidence (two sources that disagree make it disputed; where each sells does not count as disagreeing). Unknown on changes recorded before snapshots carried it; an availability change still says what it moved from and to.
• lineup reads the snapshots' lineup_urns, the topics the winning line-up names: includes is a level, true while the line-up names that topic (urn:casthq:topic:<uuid>, a team or an artist). Alone it holds on every change while true; gate it with {"change": "lineup"} in an all to fire once, when they are added. fact: "lineup" is the line-up's confidence (sources naming the same participants agree, whatever order or roles they give). Unknown on changes recorded before snapshots carried it; a lineup change still says what the line-up became.
• moved_by reads delta.start_seconds (or delta.end_seconds when the start has none). direction defaults to either.
• Unknown is not false. A change recorded before snapshots existed has no before / after; a leaf that needs them is unknown there, not of unknown is unknown, and a condition fires only when the whole is true.
• time matches a timer firing, never a change. Timers fire at the anchor plus the offset, and again (with a new generation) when the date moves; one firing per anchor time, with an id (evf_<subscription>_t<group>.<generation>) that is the same by pull and by push. when_imprecise says what to do while the anchor is coarser than a day: wait (the default) arms nothing until a day is known (a time of day, for offsets under a day); earliest and latest arm against the start and the close of the window ("Q3 2027": 1 July, 1 October). A floating time ("09:00 local, everywhere") arms when the first zone reaches it, UTC+14, unless tz names the zone to read it in. Level leaves beside a time leaf are judged on the event's state when the timer fired.
• time.at is an absolute instant ("not by 1 March"): it fires once, at that instant, and never again, however the event's date moves. Give an offset or Z (2027-03-01T09:00:00+01:00), or a wall clock without one and a tz to read it in. It must be in the future (on the test clock, in test mode) and at most 400 days ahead; otherwise the request is refused with invalid_request and param pointing at it (condition.all[0].time.at). Event and set targets; on a set it fires once for the whole set.
• members (set targets, events:a,b: 2 to 32 events you can list, in one world) and upstream (chain targets: everything the event depends on, not the event itself) aggregate a level condition over every member: all, any, or count_at_least N. On a change it fires when the aggregate goes from false to true, each member read as of that change from the change log, so a replay gives the same firings. Beside a time.at it is read as a level when the timer fires ("not both by D"). The firing carries members: made_true (the members whose condition became true at it; with once over any, the first one) and states (each member's lifecycle state).
• variant reads the event's variant value ({"region": "euw"}): every named axis must match, any listed term on it; an event that is not a variant never matches. It works on any target, and on a timer firing reads the variant that fired.
• variants:p targets are a variant parent and its variants; a variant added later joins. A time leaf there fires once per variant, never for the parent; off the parent only its own news is read (its claimed status, title, location and links, and the variants it gains), not the span it takes from its variants. members ranges over the variants, and members.where keeps only those it names.

Initial

A subscription created when its condition is already true would otherwise wait forever ("tell me when it is cancelled", asked after the cancellation). initial decides:

• fire_if_true: if the condition holds now, fire once at creation. The default for an event target whose condition has a status, state, confidence or sources leaf. Each edge is read as the level it reaches (becomes X holds while the value is X); change and time leaves never hold.
• wait: only changes from now on fire. The default otherwise, and the only choice for topic targets (an initial firing there would be one per event).

Modes

• once (the default with a condition): fires once, then the subscription is satisfied.
• continuous: fires at every change that makes the condition true.

Firing ids

A firing's id is deterministic: evf_<subscription>_<change>, or evf_<subscription>_initial. Reading the same range twice gives the same ids, so deduplicate on them.

Try one

POST https://api.casthq.co/v1/conditions/test replays a condition over an event's or topic's history and returns the changes it would have fired at. No sign-in needed for public events.