GCVE BCP-05 and Markdown format

adulau · August 5, 2026, 8:03am

Following the last discussion of the workshop about the markdown format in BCP-05, the following proposal was sent to the CVE Program:

github.com/CVEProject/cve-documents

Proposal: Add Explicit Markdown Support for CVE Record Descriptions

opened 07:59AM - 05 Aug 26 UTC

adulau

# Proposal: Add Explicit Markdown Support for CVE Record Descriptions The CVE P…rogram should support Markdown as an explicitly declared format for CVE Record descriptions. Several CVE authoring tools, including Vulnogram and other rich-text editors, already allow authors to create structured descriptions containing paragraphs, lists, links, code fragments, and other formatting. However, this structure is frequently flattened or concatenated when the content is exported into `containers.cna.descriptions[].value`. As a result, a well-structured vulnerability description can become a single wall of text. This reduces readability for analysts and makes it difficult for downstream consumers to reproduce the structure intended by the CNA. ## Current situation The CVE JSON Record Format treats the main `value` of a description as plain text. The schema also provides `supportingMedia`, which can contain an alternative HTML representation. In practice, this creates several problems: * The plain-text and HTML representations duplicate the same information. * The two representations can become inconsistent. * Many consumers ignore `supportingMedia`. * HTML requires extensive sanitisation and introduces unnecessary rendering complexity. * Rich-text editors may flatten their structured output into the plain-text description. * Consumers cannot reliably determine whether formatting characters or line breaks have defined semantics. The ongoing discussion about removing `supportingMedia` illustrates that it is not an effective or sufficiently interoperable solution for formatted vulnerability descriptions: https://github.com/CVEProject/cve-schema/issues/363 ## Proposed change Add an optional content-type property to language-aware CVE Record descriptions. For example: ```json { "lang": "en", "contentType": "text/markdown", "value": "An authentication bypass affects **Example Server**.\n\n### Affected versions\n\n- Versions before `2.4.1`\n- Version `3.0.0-beta1`\n\nThe vulnerability can be triggered through the `/api/login` endpoint." } ``` When `contentType` is absent, the value would continue to be interpreted as `text/plain`. This preserves compatibility with all existing CVE Records. Initially, the following values could be supported: * `text/plain` * `text/markdown` The exact property name could be decided by the CVE Quality Working Group, but the content format should be explicitly declared rather than inferred. ## Markdown profile The CVE Program should define a restricted and interoperable Markdown profile, based on CommonMark and a small allowlist of useful extensions. The profile should support at least: * Paragraphs and line breaks * Ordered and unordered lists * Emphasis and strong emphasis * Inline code and fenced code blocks * Links * Block quotations * Tables, when supported by the approved profile For security and interoperability: * Raw HTML should not be permitted. * Scriptable or active content should not be permitted. * Unsafe URL schemes should be rejected. * Renderers should sanitise the generated HTML. * Remote images and embedded active media should not initially be supported. * Unsupported formatting should remain readable as plain text. ## Single authoritative representation The Markdown value should be the authoritative description. Producers should not be required to publish both a plain-text copy and a Markdown copy of the same content. Maintaining two versions creates the same synchronisation problem currently encountered with `supportingMedia`. Consumers that do not support Markdown may display the source value as plain text. Markdown is intentionally designed to remain reasonably readable without rendering. If `supportingMedia` is retained, it should be reserved for genuinely supplementary media and should not be used as an alternative formatted copy of the description. ## Benefits Explicit Markdown support would: * Preserve the structure created by CVE authors. * Improve the readability of complex vulnerability descriptions. * Avoid duplicated plain-text and HTML representations. * Provide consistent behaviour across Vulnogram, CVE Services, CVE.org, GCVE and third-party tools. * Make code fragments, affected-version lists, exploitation conditions, and mitigations easier to understand. * Reduce ambiguity for downstream parsers and renderers. * Make CVE Records easier to publish directly as technical advisories or Markdown documents. * Provide a safer and simpler alternative to arbitrary HTML. ## Backward compatibility This proposal can be implemented without changing existing records: 1. `contentType` would be optional. 2. A missing `contentType` would mean `text/plain`. 3. Existing CVE Records would remain valid. 4. Existing consumers could continue reading `value`. 5. Consumers unaware of Markdown would display the Markdown source as readable text. 6. Markdown-aware consumers could render the content using the approved CVE Markdown profile. ## Documentation changes The CNA Operational Rules, particularly Section 5.2 concerning descriptions, could be updated to clarify that: * A CNA may use an approved Markdown profile for a description. * The content format must be explicitly declared. * Formatting must not replace required structured CVE Record fields. * The description must still summarise and uniquely identify the vulnerability. * Formatted content must not contradict information elsewhere in the CVE Record. * Consumers must treat unknown or unsupported content types as plain text. This would require coordinated changes in: * `CVEProject/cve-schema` * `CVEProject/cve-documents` * CVE Services and RSUS validation * Vulnogram and other CVE authoring tools * The CVE.org record renderer * Schema examples and interoperability tests ## Suggested acceptance criteria The proposal could be considered implemented when: 1. The CVE JSON schema defines an optional description content type. 2. A precise CVE Markdown profile is documented. 3. Existing records without the property remain valid. 4. Schema examples demonstrate paragraphs, lists, links, and code. 5. Raw HTML and active content are rejected. 6. Vulnogram exports structured Markdown without concatenating paragraphs or lists. 7. CVE.org safely renders Markdown descriptions. 8. Consumers have documented fallback behaviour. 9. The relationship between Markdown descriptions and `supportingMedia` is clarified. ## Conclusion CVE descriptions are technical documents written for both humans and machines. Plain text remains useful as a baseline, but it is insufficient for many modern vulnerability descriptions. Adopting this capability in the common CVE Record Format would also allow derived and compatible formats, including GCVE-BCP-05, to support structured descriptions without introducing additional extension namespaces or incompatible representations. Supporting a restricted, explicitly declared Markdown format would preserve author intent, improve readability, simplify interoperability, and remove the need to maintain duplicated HTML and plain-text versions of the same description.

If the answer is negative or it’s not implemented in 2026 by the CVE Program. An extension will be proposed in BCP-05 to support native markdown.