Table of Contents
1. Introduction §1
This document specifies the Document Alert Specification Format (hereafter DASF) version 1.0. DASF defines a vendor-neutral object model and JSON serialization for representing alerts about documents — specifically, about time-bound obligations attached to a document subject — together with the channels through which those alerts are to be delivered, the policies governing escalation and retry, and the closure signals returned by recipients.
DASF is intended to be transported over any substrate that can carry JSON: HTTP webhooks, message queues, S3 objects, email attachments, or chat protocols. DASF makes no assumptions about transport semantics beyond requiring lossless preservation of UTF-8 text and the structural fidelity of JSON.
DASF is intentionally narrow in scope. It is not a workflow engine. It does not encode business rules. It does not describe how a document was generated, signed, or stored. It does not replace iCalendar (RFC 5545) for general scheduling, BPMN for process modeling, or domain-specific compliance schemas. DASF describes only the alert — the moment at which a system says, "this document subject requires attention by this deadline."
1.1 Document conventions
Field names are written in snake_case. JSON keys are case-sensitive. Object types are written in PascalCase when discussed in prose. Examples in this document are non-normative; the normative source is the JSON Schema published at /spec/dasf-v1.0.json.
2. Conformance requirements §2
The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in RFC 2119 when, and only when, they appear in all capitals.
2.1 Producer conformance
A conformant DASF producer MUST emit payloads that validate against the JSON Schema published at /spec/dasf-v1.0.json. A producer MUST set dasf_version to "1.0" for payloads conforming to this revision. A producer MUST NOT include fields outside the schema unless those fields are namespaced under x_ (extension prefix); see §5.4.
2.2 Consumer conformance
A conformant DASF consumer MUST accept any payload that validates against the schema. A consumer MUST ignore any field prefixed with x_ that it does not understand, rather than rejecting the payload. A consumer SHOULD log unknown x_ fields for diagnostic purposes. A consumer MUST NOT silently transform timestamps; if local time conversion is performed, the original UTC value MUST be preserved alongside.
2.3 Forward compatibility
Implementations MUST treat unknown severity values as the nearest higher known value (e.g. an unknown "emergency" SHOULD be treated as "critical"). Implementations MUST treat unknown channel type values as a soft failure for that channel only, not for the alert as a whole.
3. Object model §3
A DASF payload is a JSON object containing exactly two top-level keys: dasf_version (string) and alert_event (object of type AlertEvent). All other normative types are reachable from alert_event.
3.1 AlertEvent
The AlertEvent object represents a single notifiable event about a single document subject. It is the root payload object.
| Field | Type | Req. | Description |
|---|---|---|---|
id | string | MUST | Globally unique identifier. Producers SHOULD use ULID, UUIDv7, or a comparable lexicographically-sortable identifier. |
severity | enum | MUST | One of info, warning, urgent, critical. See §6. |
issued_at | string (RFC 3339) | MUST | The instant the alert was generated. UTC, with explicit Z suffix. |
deadline_at | string (RFC 3339) | SHOULD | The instant by which the underlying obligation must be discharged. Omit only if the obligation is open-ended (e.g. an informational notice). |
last_reminder_at | string (RFC 3339) | MAY | The instant of the most recent prior reminder for the same alert. |
subject | DocumentSubject | MUST | See §3.2. |
channels | array of NotificationChannel | MUST | Non-empty. See §3.3. |
escalation | array of EscalationRule | MAY | Ordered. See §3.4. |
retry_policy | RetryPolicy | MAY | See §3.5. |
idempotency_key | string | SHOULD | Used by consumers to deduplicate. SHOULD be deterministic given the same logical alert. |
locale | string (BCP 47) | MAY | Default human language for the alert (e.g. en-US, ru-RU). |
tags | array of string | MAY | Free-form classification labels for routing and analytics. |
3.2 DocumentSubject
The DocumentSubject object identifies the document the alert is about and the obligation attached to it.
| Field | Type | Req. | Description |
|---|---|---|---|
type | string | MUST | A short identifier for the document class. Recommended values include InsurancePolicy, DriverLicense, USDOTAuthority, SR22Filing, UCRRegistration, HIPAABreachReport, WorkersCompPolicy, BusinessLicense, Permit, TaxFiling. Producers MAY use other values. |
identifier | string | SHOULD | Stable identifier of the document instance (e.g. policy number, USDOT number). |
jurisdiction | string (ISO 3166-2) | MAY | Issuing or governing jurisdiction (e.g. US-NY, US-CA, RU). |
obligation | string | SHOULD | The action required of the recipient. Recommended values: renewal, filing, payment, review, upload, signature, notification, response. |
human_label | string | SHOULD | Human-readable description suitable for display to recipients. |
references | array of object | MAY | External references (URIs to source documents, regulation cites, etc.). |
3.3 NotificationChannel
Each entry in alert_event.channels is a NotificationChannel describing one delivery target.
| Field | Type | Req. | Description |
|---|---|---|---|
type | enum | MUST | One of email, sms, push, webhook, voice, postal. See §8. |
address | string | MUST | The channel-specific delivery address. Format constrained by type. |
locale | string (BCP 47) | MAY | Recipient locale override. |
quiet_hours | string | MAY | Local quiet window, format HH:MM-HH:MM TZ per IANA time zone (e.g. 22:00-07:00 America/New_York). |
signed | boolean | MAY | For webhook channels: indicates the consumer requires HMAC signature on delivery. |
options | object | MAY | Channel-specific delivery options (e.g. {"reply_to": "..."} for email). |
3.4 EscalationRule
The escalation array describes ordered reactions to non-acknowledgement. Rules are evaluated in array order; the first rule whose after duration has elapsed since issued_at and whose precondition is met is applied.
| Field | Type | Req. | Description |
|---|---|---|---|
after | string (ISO 8601 duration) | MUST | Elapsed time since issued_at at which the rule fires (e.g. P7D, PT12H). |
action | enum | MUST | One of resend, escalate, elevate_severity, cancel. |
severity | enum | MAY | New severity for elevate_severity or resend. |
to | string | MAY | For escalate: alternate channel address (e.g. supervisor email). |
channel_type | enum | MAY | For escalate: optional channel type override. |
condition | enum | MAY | One of not_acknowledged (default), not_delivered, not_completed. |
3.5 RetryPolicy
The retry_policy object describes channel-level delivery retry behavior — distinct from escalation, which addresses recipient inaction.
| Field | Type | Req. | Description |
|---|---|---|---|
max_attempts | integer | MUST | Total delivery attempts including the first. MUST be in range 1–20. |
backoff | enum | MUST | One of fixed, linear, exponential, exponential_jitter. |
initial_delay | string (ISO 8601 duration) | SHOULD | Delay before second attempt. Default PT30S. |
max_delay | string (ISO 8601 duration) | MAY | Cap on backoff. Default PT1H. |
3.6 AcknowledgementReceipt
The AcknowledgementReceipt object is returned by recipients (or their agents) to close an alert loop. Receipts are themselves DASF payloads with alert_event.subject.obligation = "response" and an x_ack_for field referencing the original AlertEvent.id. Producers MUST treat any of the following as terminal: x_ack_status = "acknowledged" | "completed" | "dismissed"; "snoozed" is non-terminal and MUST include x_snooze_until.
4. Required fields §4
The minimal valid DASF payload contains the following required fields:
dasf_version— MUST equal"1.0"for payloads conforming to this document.alert_event.id— MUST be a non-empty string.alert_event.severity— MUST be one of the enum values in §6.alert_event.issued_at— MUST be an RFC 3339 timestamp in UTC.alert_event.subject.type— MUST be a non-empty string.alert_event.channels— MUST be a non-empty array; each element MUST containtypeandaddress.
5. Optional fields §5
5.1 Recommended optional fields
The following fields are not required but SHOULD be supplied when meaningful, because consumers and downstream AI agents derive significant value from them:
deadline_at— without this, the alert cannot participate in deadline-driven scheduling.subject.identifier— without this, deduplication across producers is impossible.subject.jurisdiction— required for any locale-aware presentation or regulator routing.subject.obligation— required for downstream prioritization heuristics.idempotency_key— required for safe retransmission across producer restarts.
5.2 Subject references
Each entry in subject.references is an object with at minimum a uri field. Recommended additional fields: rel (e.g. "source", "regulation", "contract"), media_type (RFC 6838).
5.3 Tags
The tags array is intentionally unconstrained. Recommended convention: lowercase, kebab-case, with namespace prefix where useful (e.g. fmcsa:ucr, hipaa:breach, insurance:auto).
5.4 Extension fields
Any field whose key begins with x_ is an extension field. Producers MAY add extension fields anywhere in the payload. Consumers MUST NOT reject a payload solely because it contains unknown x_ fields. Extension fields are not registered centrally; coordination between producer and consumer is out of scope for DASF v1.0.
6. Severity levels §6
DASF defines four severity levels. Producers MUST select exactly one. Consumers SHOULD apply progressively stronger delivery and presentation behaviors as severity increases.
| Value | Meaning | Typical use |
|---|---|---|
info | Informational; no action required by the recipient. | Confirmation that a renewal was processed; status notice. |
warning | Action will be required, but the deadline is not imminent. | Policy expires in 90 days; license renewal window opens. |
urgent | Action is required soon; missing the deadline has material consequences. | Policy expires in 14 days; SR-22 filing in 7 days. |
critical | Deadline is imminent or has been crossed; non-action triggers regulatory or contractual breach. | HIPAA breach 60-day clock at T-7; UCR enforcement begins tomorrow. |
Severity is independent of escalation. An info alert MAY have an escalation rule. A critical alert MAY have none.
7. Time semantics §7
All DASF timestamps are RFC 3339 strings. Producers MUST use UTC and the explicit Z suffix; producers MUST NOT use offset notation such as +00:00. Consumers MAY convert to local time for display, but MUST preserve the UTC value for storage and re-transmission.
7.1 Timestamp fields
issued_at— the instant the producer generated the alert. SHOULD reflect the producer's wall clock at generation, not at transmission.deadline_at— the instant by which the underlying obligation must be discharged. SHOULD reflect the regulator's or counterparty's stated deadline, not a derived "remind me by" target.last_reminder_at— for repeated alerts, the instant of the previous transmission for the same logical event.
7.2 Durations
Escalation after values and retry initial_delay/max_delay values are ISO 8601 durations. Common forms: PT30S (30 seconds), PT5M (5 minutes), PT1H (1 hour), P1D (1 day), P7D (7 days), P30D (30 days). Calendar-aware durations (P1M, P1Y) are PERMITTED but consumers SHOULD treat them as approximate (30 and 365 days respectively) unless they have access to the producer's reference calendar.
7.3 Quiet hours and time zones
The quiet_hours field on a channel is interpreted in the named IANA time zone. Consumers MUST defer delivery until the next non-quiet local minute. Quiet hours MUST NOT apply to critical severity alerts.
8. Channel adapters §8
DASF defines six channel types. Address format is constrained per type. Future revisions MAY add channel types; consumers MUST treat unknown channel types as a per-channel soft failure (see §2.3).
| Type | Address format | Notes |
|---|---|---|
email | RFC 5322 mailbox | Address MUST be a single mailbox; lists are out of scope. |
sms | E.164 (e.g. +13158710833) | Producers SHOULD respect carrier rate limits. |
push | Opaque token | Format is platform-defined (FCM token, APNs device token, web push endpoint URL). |
webhook | HTTPS URL | Plain HTTP MUST NOT be used. If signed = true, HMAC-SHA256 signature MUST be sent in X-DASF-Signature header. |
voice | E.164 | Voice channels SHOULD include options.script_uri for speech text. |
postal | Address book identifier | Out-of-band postal mail. Address format is implementation-defined. |
8.1 Webhook delivery
Webhook deliveries MUST POST the full DASF payload as the JSON request body with Content-Type: application/json; charset=utf-8. The HTTP request MUST include header X-DASF-Version: 1.0. If the channel has signed = true, the request MUST include X-DASF-Signature: sha256=<hex> where the HMAC is computed over the raw request body using a pre-shared secret negotiated out of band. Consumers SHOULD respond with HTTP 200, 202, or 204 within 30 seconds; any other response MUST be treated as a delivery failure subject to retry_policy.
9. JSON serialization §9
DASF payloads MUST be valid RFC 8259 JSON encoded as UTF-8 with no byte-order mark. Whitespace is insignificant. The canonical form for hashing (used in idempotency_key derivation) is JCS (RFC 8785) but consumers MUST NOT require canonical form for delivery acceptance.
9.1 Schema
The normative JSON Schema is published at /spec/dasf-v1.0.json and conforms to JSON Schema 2020-12. Producers and consumers MAY validate payloads with any compliant validator (ajv, jsonschema, everit-org/json-schema, etc.).
10. Example payloads §10
Six worked, jurisdiction-grounded payloads are published at /examples/. The minimal example below demonstrates a conformant payload using only the required fields plus the recommended optional fields; it MUST validate against the schema.
{
"dasf_version": "1.0",
"alert_event": {
"id": "evt_01HZX9N7Q4M2K8VYP3FA5GTRBC",
"severity": "warning",
"issued_at": "2026-04-29T15:00:00Z",
"deadline_at": "2026-07-28T05:00:00Z",
"idempotency_key": "renewal:POL-99381-A:2026-07-28",
"subject": {
"type": "InsurancePolicy",
"identifier": "POL-99381-A",
"jurisdiction": "US-NY",
"obligation": "renewal",
"human_label": "Commercial Auto Policy — ACME Trucking LLC"
},
"channels": [
{ "type": "email", "address": "ops@acmetrucking.example" }
]
}
}11. Versioning policy §11
DASF follows a two-level version: major.minor. The dasf_version field carries the version string in the form "MAJOR.MINOR".
- Minor revisions are backward-compatible. They MAY add optional fields, add enum values, or relax existing constraints. Conformant v1.0 consumers MUST accept v1.1, v1.2, … payloads.
- Major revisions are breaking changes. A v2.0 payload MUST NOT be sent to a v1.x consumer that has not negotiated v2.0 acceptance.
- Errata are corrections to text without semantic change. Errata do not change
dasf_version.
dasf_version they have not been certified against. Consumers MUST reject payloads with a dasf_version whose major version they do not implement.12. Security considerations §12
12.1 Personally identifiable information
DASF payloads commonly contain identifiers (policy numbers, USDOT numbers, license numbers) that constitute PII or PHI in their respective jurisdictions. Producers and consumers MUST evaluate applicable regimes (HIPAA, GDPR, GLBA, FERPA, FCRA) and apply at-rest encryption, transport encryption, access controls, and retention limits accordingly. DASF does not specify these controls; it only carries the data.
12.2 Transport security
Webhook channels MUST use HTTPS. Producers SHOULD pin to TLS 1.2 or higher. Consumers SHOULD validate certificates against a current trust store and SHOULD NOT accept self-signed certificates outside controlled lab environments.
12.3 Authentication and integrity
When channels[i].signed = true for webhook channels, the producer MUST sign the body with HMAC-SHA256 and a shared secret. Consumers MUST verify the signature in constant time and MUST reject payloads with invalid signatures. Secret rotation policy is out of scope for DASF v1.0.
12.4 Replay and idempotency
Consumers MUST treat repeated payloads with the same idempotency_key as a single logical alert. Consumers SHOULD retain the most recent id observed for each idempotency_key for at least 30 days.
12.5 Right to erasure
When applicable law (e.g. GDPR Article 17) requires erasure of PII contained in DASF payloads, both producer and consumer MUST be able to expunge by subject.identifier within the timelines required by that law. DASF imposes no obligation to make this efficient; it acknowledges only that the data structure must not impede compliance.
13. References §13
13.1 Normative references
- RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels.
- RFC 3339 — Date and Time on the Internet: Timestamps.
- RFC 5322 — Internet Message Format.
- RFC 6838 — Media Type Specifications and Registration Procedures.
- RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format.
- RFC 8785 — JSON Canonicalization Scheme (JCS).
- JSON Schema 2020-12.
- ISO 8601 — Date and time format.
- IANA Time Zone Database.
13.2 Informative references
- RFC 5545 — Internet Calendaring and Scheduling Core Object Specification (iCalendar).
- HIPAA Breach Notification Rule (45 CFR §§164.400–414).
- FMCSA Unified Carrier Registration.
- NIST SP 800-63-3 — Digital Identity Guidelines.
- BPMN 2.0 — Business Process Model and Notation.
13.3 Acknowledgements
DASF was developed by the DocSiren Working Group at Zakonno Inc with input from compliance practitioners in motor carrier regulation, insurance back-office operations, and healthcare privacy administration. The format draws conceptual inspiration from RFC 5545 (iCalendar) and the OpenTelemetry log data model.
End of DASF v1.0 normative text. Errata, schema source, and example payloads are linked above.