CSAF 2.0 defines seven note categories: description, details, faq, general, legal_disclaimer, other and summary. Use summary for the short answer, description for what the flaw is, details for depth, faq for common questions, and legal_disclaimer for terms. Use general and other sparingly.
Definition
The Common Security Advisory Framework, or CSAF, is an OASIS standard dated 18 November 2022. It defines a JSON format for security advisories so customers' tools can read them. The only mandatory top level property is document, while product_tree and vulnerabilities are optional.
Notes are free text blocks inside that structure. Each note carries a category, which tells a reader or a tool what kind of text it is.
The seven categories
| Category | Use it for |
|---|---|
| summary | A two or three sentence statement of what happened and who is affected |
| description | What the flaw is and where it lives |
| details | Longer technical explanation, root cause, conditions |
| faq | A list of frequently asked questions |
| general | Context that does not fit elsewhere |
| legal_disclaimer | Terms and liability wording |
| other | Anything that fits none of the above |
The specification says the faq value indicates the note is a list of frequently asked questions, which makes it a natural home for the same Q and A block you show on the web page.
Mapping a human advisory to notes
An advisory page usually has the same parts every time. Map them once and reuse the mapping.
- Opening paragraph, 40 to 60 words, becomes the summary note.
- The section describing the flaw becomes description.
- Root cause and reproduction conditions become details.
- The Q and A block becomes faq.
- Your standard terms become legal_disclaimer.
Keep the web page and the CSAF file in sync. If they disagree, customers will trust neither. Our post on CSAF status and version numbers covers how to track changes.
Why the summary note is worth the effort
Tools and people both read the shortest field first. A clean summary lets a customer's system show a useful line without parsing prose. Write it as a direct answer: what is affected, what to do, and the date.
What to avoid
- Putting remediation steps only in a note. Steps customers need to automate belong in the structured fields, not just in text.
- Using other as a dumping ground.
- Pasting marketing language into a summary.
Quick check
How many note categories does CSAF 2.0 define?
Seven: description, details, faq, general, legal_disclaimer, other and summary.
Is every CSAF property mandatory?
No. In the excerpt of the specification we reviewed, document is the only mandatory top level property, but nested fields have their own rules, so validate against the schema.
Safeguard's SBOM and dependency scanning help vendors know which products an advisory touches before they write it. The free scan is at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
