Schemas & Scheduling — Aggregated Schema, Override Schemas, Scheduled and Future-Date Triggers

TL;DR

• Every step can reference only its aggregated schema (trigger payload + ancestor outputs + setVariable.* + identity enrichment) — build it yourself, per step (Automations Graph and Data Model §4).
• Dynamic schemas: trigger payload grows with its filters; an action's inputs grow with updateSchemaOnChange fields; its outputs grow with its mapping. Fetch them — never invent fields.
• Override output schema is allowed ONLY on: triggers wix_automations-webhook_trigger, wix_automations-custom_trigger; actions webhooks-action, wix_automations-llm_call, ai_custom_agent_bm-delegate_to_agent. Wire fields: trigger.overrideSchema, appDefinedInfo.overrideOutputSchema.
• Scheduled trigger: trigger.automationConfigMapping = { startDate, repetitions? { cronExpression, everyNthDay | everyNthWeek | everyNthMonth, endDate? } }. No repetitions = one run. Use the exact site's IANA time zone from current tool-returned metadata, with Site Properties as fallback (§4). Create and Update support automationConfigMapping; include it in the trigger configuration.
• "N days before the event" = trigger.scheduledEventOffset (only for triggers with a futureDate field). "After" = a DELAY step (Automations Delays Variables and Branches).

1. The aggregated schema

Each step may read only its aggregated schema: the trigger payload (override, or static + dynamic merged) + outputs of its ancestor steps under their namespace + setVariable.* + identity enrichment — never a sibling branch, a descendant or a skipped step. Full recipe, identity-enrichment keys and resolution order: Automations Graph and Data Model §4. Only its paths may appear in a step's var("…") expressions (Automations Mapping Expressions).

2. Dynamic schemas — markers

A field you need but cannot see is unknown until its controlling selection is made — say which selection reveals it; don't claim the data doesn't exist, and don't invent it. Form answers with no form filter chosen are such fields: use only static fields, or ask which form (Automations Trigger Configuration §5).

3. Override output schema

Replaces a component's schema so downstream steps get addressable fields. It exists only for components whose data comes from outside Wix and therefore have no schema of their own.

NEVER add an override to any other trigger or action — including one with a dynamic output schema (that schema is real; fetch it). If an existing automation already carries an override on another component, leave it untouched.

Generate one only when a downstream step consumes the data ("then use…", "based on the result…"). Skip it when the component is the last step or its default schema suffices.

Schema requirements (both kinds):

• JSON Schema draft-07: "$schema": "http://json-schema.org/draft-07/schema", root "type": "object", properties, required; standard types only; give each property a title.
• Trigger overrides: one realistic examples entry per property.
• A trigger overrideSchema replaces the payload schema. An action overrideOutputSchema is merged over the catalog output schema (its properties win on a clash) — catalog output fields stay addressable. Get Automation returns overrides only with fields: ["OVERRIDE_SCHEMA"] — use it on read-back, or the override looks lost. For the webhook trigger keep the webhookId property in the override if the validator reports it missing. Webhook wiring (id, filter, config mapping) and the custom trigger's hookId: Automations Trigger Configuration §6.

Per-action rules:

• LLM (wix_automations-llm_call): when a property is a decision among known outcomes that a later condition branches on, constrain it with enum (e.g. "location": {"type": "string", "enum": ["inside", "outside"]}) — the condition can only match values it can predict.
• LLM / custom agent — input grounding: the override describes the result, not the source data. Put the concrete, schema-verified {{var("…")}} values into the prompt/instructions input. "Analyze the order" without mapping the order fields is incomplete even if it validates.
• Custom agent: the schema must match the agent's task ("check loyalty eligibility" → isEligible, discountPercentage, reason, not generic success). Change the schema when the instructions change.
• Webhook action: model the called API's response (data / status / timestamp).

4. Scheduled trigger (wix_automations-scheduled_trigger, app 139ef4fa-c108-8f9a-c7be-d5f492a2c939)

Timing lives in configuration.trigger.automationConfigMapping, supported by Create and Update and required by the builder. Read the trigger's automationConfigSchema from Get Trigger By App Id And Key and follow it if it differs. The scheduled trigger carries no payload data — only timing.

startDate (required): YYYY-MM-DDTHH:mm:00±HH:MM — seconds 00, no milliseconds, the site time zone's offset on that date (Z only if the site is UTC). Its hour

Time zone: use the IANA zone in current tool-returned site metadata for the exact target site, if supplied; otherwise read Site Properties — GET https://www.wixapis.com/site-properties/v4/properties?fields.paths=timeZone (SDK siteProperties.getSiteProperties({fields: ["timeZone"]}) from @wix/business-tools) → properties.timeZone (IANA, e.g. America/New_York). Convert it to the offset valid on each date (DST changes the offset; compute startDate and endDate separately). If neither source supplies a valid zone, ask the user; never use another site’s zone, a documentation example, memory or a silent UTC default.

A schedule always runs in the site's time zone. If the user names a different zone ("23

One-time: {"startDate": "…"} only — the absence of repetitions means run once (and no endDate).

Recurring: repetitions with cronExpression + exactly one of everyNthDay (1–99) / everyNthWeek (1–52) / everyNthMonth (1–12) — the stricter of the builder's input (1–99) and the trigger's config schema (≤ 365 days, 52 weeks, 12 months), optional endDate inside repetitions (same format and time zone, after startDate). Cron is "MM HH DOM MON DOW" (Sunday = 0); N#K = Kth weekday N of the month; NL = last weekday N.

Builder round-trip (it regenerates the cron from startDate when the panel opens — any mismatch is rewritten):

• cron MM HH = startDate's minute and hour, no leading zeros ("0 9 …", not "00 09 …").
• Weekly weekdays in ascending order (1,3,5). Monthly day-of-month = startDate's day; N#K: N = startDate's weekday, K = its week of the month (days 1–7 → #1, 8–14 → #2, …).
• Known builder issues (tell the user): opening the schedule panel can rewrite NL to MM HH L * * and resets an endDate to exactly one year after startDate; a save after opening it persists that. Ask them to re-check both before saving from the builder.

Weekly: pure interval → everyNthDay: 7/14/21 (runs on startDate's weekday); specific weekday(s) → everyNthWeek + cron DOW.

Monthly (most restrictive): startDate MUST itself be an instance of the pattern (a "15th" schedule starts on a 15th; "first Monday" starts on a first Monday). Only two patterns exist: day-of-month 1–28, or weekday position #1–#4 / L.

Not supported — say so and offer an alternative:

• Last day of month (L in day-of-month) — never write it, even though the builder's panel offers a "last day" option when startDate is a month's last day: it is not a supported pattern. Offer: a daily schedule + a month-end check (below; the only one that fires on the real last day), day 28 (fires up to 3 days early), a last-weekday position (5L), or the 1st.
• 29th/30th/31st, several days per month, "second-to-last X".
• More than once a day (hourly/minutes).
• Two everyNth* params together, or repetitions with none.

Daily + month-end check (for "last day of month" or other calendar rules the schedule can't express): a daily schedule (everyNthDay: 1) whose root is a CODE_CONDITION (Automations Conditions §5) with dynamicVariableExpressions: [] (the scheduled trigger has no payload) and the site time zone written into the code:

Replace <SITE_TIME_ZONE> with the site's validated IANA time zone before saving; do not save the placeholder. Validate the site's IANA time zone before saving; an invalid or unavailable zone is a blocker, never a reason to use UTC. The runtime guard returns false if date formatting fails. Compare calendar dates as above: adding 24 hours is not "tomorrow" across daylight-saving changes. Keep the JSDoc header and the complete snippet within 1000 characters per Automations Conditions §5; put the real steps on its true branch, [] on the false one. Tell the user the check runs in code.

Checklist: startDate matches the pattern day • cron consistent with the everyNth* param • offsets correct for the site time zone on each date • monthly pattern exists in every month • when in doubt prefer daily/weekly over monthly.

5. Future-date offset ("before the event")

For triggers whose payload has a date-time field with futureDate: true (e.g. session start), run the automation a fixed time before that date:

• For a builder-editable fixed reminder, use a positive integer literal {{N}}, unit MINUTES | HOURS | DAYS | WEEKS | MONTHS. Omit scheduledEventOffset entirely when there is none.
• The public scheduled-events contract also supports payload-driven expressions such as {{var("timeOffset")}}. This is an API capability, but the current builder's timing panel and canvas label recognize only a numeric expression: a variable will not display as the requested reminder window. Do not silently replace a payload-driven request with a fixed number; explain that editor limitation and ask whether a fixed, editable window is acceptable. Preserve an existing variable expression unchanged during unrelated updates; do not rewrite its timing to make the panel display it.
• Offsets are always before the event. "2 days after the booking" → no offset; add a DELAY step (Automations Delays Variables and Branches).
• A trigger without a futureDate field cannot take an offset.

6. Custom API ("site") actions

Site actions (wix_automations-wix_api_integration) are generated through non-public services and can't be created from public APIs — a limitation (§1 of Automations Feasibility and Planning (topic guide not yet published; consult the Automations API reference)). Leave an existing one's inputMapping untouched.