Venn / Euler diagram

About Venn and Euler diagrams

A Venn diagram uses overlapping circles to show every possible logical relationship among a collection of sets — whether or not each intersection actually contains any elements. A Euler diagram is the more general form: circles are only drawn where relationships actually exist, so a set fully contained in another is shown as a nested circle, and two disjoint sets do not overlap at all. John Venn introduced the fixed-overlap form in 1880; Leonhard Euler described the general set-containment form in the 1760s.

Educators use them to teach set theory; data analysts reach for them to show audience overlap between segments (email list ∩ mobile users ∩ paid subscribers); researchers in biology, linguistics, and medicine use Euler diagrams to map taxonomic or conceptual hierarchies. Schematex supports all four common usage patterns in one DSL — declarative counts, element enumeration, region labels, and Euler subset/disjoint/overlap relations — and can mix them in a single diagram. See the Wikipedia article on Venn diagrams and Euler diagrams for background.

1. Your first Venn diagram

The smallest useful diagram: two sets, one overlap, two exclusive regions.

Four rules cover 80% of usage:

1. Start with venn, optionally followed by a quoted title.
2. Declare each set with set ID "Label" — the id is used internally, the label appears in the diagram.
3. Assign values to regions using A & B : value for intersections and A only : value for exclusive regions.
4. Configure appearance with config: lines; the diagram mode (venn vs euler) can be set explicitly or left as auto.

Comments must start with # on their own line.

2. Sets

A set declaration creates one circle in the diagram.

set ID "Label" [color: "#hex"]

Sets must be declared before they are referenced in region or relation lines.

3. Regions

A region assigns a value to an intersection or exclusive area. The four DSL modes can be mixed in one diagram.

3.1 Declarative mode — counts and percentages

Assign a number or percentage to a named region. The region key is either an &-separated list of set ids (for intersections) or ID only (for the part of that set not covered by any other set).

A & B : 320          # integer count
A & B & C : 45       # three-way intersection
A only : 1450        # A minus all other sets
A & B : 18.5%        # percentage value

3.2 Region labels (text)

Use the region keyword prefix and assign a quoted string instead of a number. The string is rendered inside the region.

region A & B : "Nurture"
region B & C : "Convert"
region A & B & C : "Loyal customer"

3.3 Enumeration mode — element lists

List the actual elements of each set. Schematex computes all intersections automatically.

ID = { element1, element2, element3 }

Elements are comma-separated bare words or quoted strings. Enumeration sets do not need an explicit set declaration — the declaration is implied.

4. Euler relations

Euler relations express structural containment or separation — that one set is a subset of another, that two sets are completely disjoint, or that they merely overlap. They must reference set ids already declared with set.

from subset to    # from is fully inside to (also: "in")
from in to        # alias for subset
from disjoint to  # from and to do not overlap
from overlap to   # from and to partially overlap (explicit — the default for unrelated sets)

5. Configuration

config: lines tune diagram behavior. Each goes on its own line.

Config can also be written inline on the header line: venn "Title" [proportional: true, showPercent: true].

venn "Segment overlap"
config: proportional = true
config: showPercent = true
config: blendMode = screen

Layout selection:

• layout venn — alternative form of config: diagram = venn (parses identically).
• layout euler — alternative form of config: diagram = euler.
• layout auto — alternative form of config: diagram = auto.

6. Labels & comments

• Title: venn "My diagram" — first line only.
• Set label: set A "Email subscribers" — quoted string on the set line.
• Region value: integer, percentage, quoted string, or element list assigned after the :.
• Comments: # at the start of a line (after leading whitespace).

7. Reserved words & escaping

Reserved at line start: venn (header), set, config:, layout, region.

Reserved operators in region keys: & (intersection), only (exclusive region).

Euler relation keywords: subset, in, disjoint, overlap — cannot be used as set ids.

ID rules: must match [A-Za-z][A-Za-z0-9_-]*. Labels with spaces go in the quoted "Label" field.

8. Common mistakes

9. Grammar (EBNF)

document       = header (blank | comment | config | layout-stmt | set-decl | enum-decl | euler-rel | region)*

header         = "venn" ( ":"? WS quoted-string )? ( WS "[" config-props "]" )? NEWLINE
quoted-string  = '"' any-char-but-quote* '"'

config         = "config" WS ":" WS config-key WS "=" WS config-value NEWLINE
config-key     = "diagram" | "proportional" | "palette" | "blendMode" | "showCounts" | "showPercent"

layout-stmt    = "layout" WS ( "venn" | "euler" | "auto" ) NEWLINE

set-decl       = "set" WS id WS quoted-string ( WS "[" set-props "]" )? NEWLINE
set-props      = "color:" quoted-hex | "fill:" quoted-hex

enum-decl      = id WS "=" WS "{" element-list "}" NEWLINE
element-list   = element ( "," element )*
element        = quoted-string | bare-word

euler-rel      = id WS euler-op WS id NEWLINE
euler-op       = "subset" | "in" | "disjoint" | "overlap"

region         = "region"? WS region-key WS ":" WS region-value NEWLINE
region-key     = id WS "only"
               | id ( WS "&" WS id )+
region-value   = integer | percent | quoted-string | "[" element-list "]"

percent        = number "%"
id             = [A-Za-z] [A-Za-z0-9_-]*
comment        = "#" any NEWLINE

Authoritative source: src/diagrams/venn/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

10. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• Three-way and N-way Euler nesting — the renderer currently supports up to 3 sets in Venn mode; larger Euler diagrams with complex containment are not yet fully laid out.
• fill: color alias — the fill: property on set is accepted by the parser (as an alias for color:) but the renderer currently only uses color:.
• label: on regions — region A & B [label: "Core"] syntax for separate label vs. value.
• Area-proportional Euler — proportional: true currently only affects Venn mode; Euler containment layout ignores the flag.
• and keyword — natural-language A and B : 120 as alias for A & B : 120.

Track in the GitHub issues if you need any of these sooner.