Corporate action schema
The JSON document describes one version of one corporate action. JSON Schema defines its structure. The content specification also defines rules that depend on context, such as checking the announcement source and comparing revisions.
Example: a cash dividend
An issuer pays a cash dividend of USD 0.50 for each underlying share. Holders on the record date on April 15 get paid on April 30. The issuer publishes this document:
{
"schemaVersion": "1",
"category": "corporateAction",
"eventId": "example:2027:dividend-q1",
"eventRevision": 1,
"announcementId": "example:2027:dividend-q1",
"notificationType": "NEWM",
"processingStatus": { "complete": true, "confirmed": true },
"publishedAt": "2027-04-01T09:00:00Z",
"asset": {
"token": "eip155:1/erc20:0x0000000000000000000000000000000000000001",
"underlying": [{ "type": "ISIN", "value": "US0000000001" }]
},
"event": {
"eventType": "DVCA",
"mandatoryVoluntary": "MAND",
"summary": "Cash dividend of USD 0.50 for each underlying share."
},
"dates": [
{ "type": "RecordDate", "value": "2027-04-15T20:00:00Z" },
{ "type": "PayDate", "value": "2027-04-30T16:00:00Z" }
],
"options": [{
"number": 1,
"type": "CASH",
"isDefault": true,
"currency": "USD",
"movements": [{
"number": 1,
"direction": "credit",
"assetType": "cash",
"currency": "USD",
"amounts": [{
"type": "GrossDividendRateAmount",
"value": "0.50",
"currency": "USD"
}]
}]
}]
}
asset,eventId, andeventRevisionidentify the token, the dividend, and this version of it.eventsays what the action is: a mandatory (MAND) cash dividend (DVCA).datesandoptionsgive the terms: when it applies and what each holder receives for each share.notificationTypeNEWMmarks this as the first notice. A later correction usesREPLwitheventRevision2.
The sections below explain each part.
Identify the asset, event, and version
The envelope separates three kinds of identity:
asset.tokenidentifies the token and network in CAIP-19 format.asset.underlyingidentifies the underlying security, for example by ISIN.eventIdidentifies the corporate action and stays the same across revisions. It is unique for the asset, not globally.announcementId, when present, matches the onchain announcement'sid.
schemaVersion is "1" and category is "corporateAction". These identify the document format. eventRevision identifies the version of the action: it starts at 1 and increases with each later version. publishedAt records when the publisher made that version.
Describe the action
event.eventType identifies the kind of action. Examples include DVCA for a cash dividend, SPLF for a forward split, and MEET for a shareholder meeting. event.summary explains it in plain language.
The announcement's description should use the same text as event.summary. The summary is English unless event.summaryLanguage specifies another language. Publishers can supply event.summaryTranslations; readers should show a matching translation when available and otherwise use the summary.
Different actions use the same structure but supply different terms. A dividend can include an amount for each underlying share. A split can include a new-to-old share ratio. A meeting has resolutions and a voting-service link.
Most terms appear in typed lists. Each entry names what its value means. For example, this excerpt distinguishes the record date from the payment date:
{
"dates": [
{ "type": "RecordDate", "value": "2027-04-15T20:00:00Z" },
{ "type": "PayDate", "value": "2027-04-30T16:00:00Z" }
]
}
This is an excerpt, not a complete document. Terms can apply to the event, an option, or a movement. Their location defines their scope. A movement's payment date applies to that movement.
Use decimal strings for financial values, such as "0.50", to preserve precision. Revision and option numbers remain integers. Dates include a time and time-zone offset. Currencies use ISO 4217 codes or CAIP-19 identifiers for onchain assets.
Describe holder participation
event.mandatoryVoluntary distinguishes:
MAND: the action applies without an election.CHOS: the action applies, but the holder can choose an option. Exactly one default option applies if the holder does nothing.VOLU: participation requires an election.
An option describes a choice. Its movements describe what the holder gives or receives if that option applies. These are terms, not evidence of settled transfers. Every option has isDefault, and at most one option can be the default. Readers must not assume the first option is the default. Options marked Cancelled or Inactive are unavailable.
For NEWM, REPL, and RMDR notices, non-meeting events require at least one option, while meeting events require a meeting block and a RecordDate. Meeting documents must not contain options.
The meeting block describes the meeting time, voting deadline, voting-service URI, and resolutions. The voting deadline must precede the meeting. The voting service handles sign-in, eligibility, and submission. Individual votes do not belong in the public document.
Follow revisions
The publisher keeps the same event ID, announcement ID, and URI. Each later document has a higher eventRevision. Readers retrieve the document again when the announcement is updated.
| Notification | Meaning |
|---|---|
NEWM | A new notice. |
REPL | Replaces the earlier terms in full, not as a partial patch. |
RMDR | A reminder that does not change the terms. |
CANC | Cancels the earlier revision named in cancelsRevision, not the event. Stop using that revision's terms until a later NEWM or REPL arrives. |
WITH | Withdraws the event. No later revision uses that event ID. |
Readers keep the highest revision for the asset and event. They do not replace it with a lower or equal revision. If the same revision has different content, readers reject that content and should warn the user.
processingStatus.complete means all terms are known. processingStatus.confirmed means the issuer confirmed the event. Neither field proves payment, execution, or an irreversible lock against later revisions.
Relate terms to onchain effects
The optional effects list describes expected token changes, such as a multiplier change. executed is true only when the announcement or its update brackets the actual change. Readers should compare declared effects with the associated state-change records.
A future effectiveAt date is a schedule, not proof that execution occurred.
Extensions, alternate formats, and privacy
The format uses ISO corporate action vocabulary and BRx type names. Optional alternates can link to the same event version in another format, such as ISO 20022 XML. If an alternate disagrees, readers use the corporate action JSON document. If an alternate supplies a hash, readers verify it before use.
The schema permits x- extension fields at the top level, in options, and in movements. A typed-list entry's type can also use an x- extension name. Readers ignore extension fields they do not recognize. This does not permit arbitrary new values for fields such as event.eventType or an option's type.
Documents contain public event terms, not holder-specific accounts, balances, entitlements, elections, or votes. Render summaries and narratives as plain text, never as HTML or script.
For exact field definitions, see JSON Schema.