In VEX, version numbers and timestamps are how consumers detect change. The rules are simple: any content change bumps the document version, a changed statement bumps its own version, and the document's last updated time can never be older than its newest statement. Break these and automated consumers miss updates.
Why this matters
CISA notes that it does not specify how or when to exchange VEX information. Timestamps and versions are intended to support change notification and tracking. So every consumer that polls a feed relies on them. If an author edits a status without bumping a version, a downstream tool that compares versions will see no change.
Document level rules
From CISA's minimum requirements:
- A document must include one document version, and it must be incremented when any content changes, including content inside statements.
- The version must clearly convey positive incremental change.
- A document must record when it was first issued, and that time must equal the oldest first issued time of its statements.
- The last updated time must initially equal first issued, and must be equal to or newer than the most recent statement update.
Statement level rules
- Each statement must have a version that increments when its content changes.
- Each statement must record first issued and last updated times.
- The statement's last updated time starts equal to first issued.
Statement versions may be derived from or related to the document version, but they are tracked separately. If document metadata such as tooling or author role changes, the document version and time move forward while statements stay as they were.
What OpenVEX adds
OpenVEX requires a document timestamp and version, and treats the statement version as an optional integer that defaults to zero and must be present once incremented. Timestamps inherit downward: a statement timestamp overrides the document timestamp. When you update a document, statements you did not touch must keep their original data, and if the document timestamp changes, those statements should carry their original timestamp explicitly.
All time values should follow common standards. CISA names RFC 3339 as an example.
A worked update
You publish a document at version 1 with three statements. A week later one statement moves from under_investigation to fixed.
- Document version becomes 2.
- The changed statement's version increments, and its last updated time is now.
- The two other statements keep their old versions and times.
- The document's last updated time equals the changed statement's time.
Consumer tip
Store the last version you processed. On each fetch, if the version is higher, diff the statements and look only at those with a newer last updated time.
Quick check
Do I bump the version if I only fix a typo in a note?
Yes. CISA says the document version must increment when any content changes.
Should I reset first issued when I republish?
No. First issued records when the statement first appeared and should stay put.
Sources
Last reviewed: 19 October 2026.
