Ecomap

About ecomaps

An ecomap is a single page that shows a person or family at the center and the web of outside systems — extended family, school, church, clinic, employer, support groups — arrayed around them. Each connecting line records the quality (strong, tenuous, stressful) and direction (who gives, who takes) of the relationship. Social workers, school counselors, case managers, and community-health nurses use ecomaps to see at a glance where a client has anchors and where the safety net is thin.

Schematex follows the Hartman (1978) ecomap model — the original Social Casework paper that introduced the notation — extended with conventions from contemporary clinical social work practice. For background see Wikipedia: Ecomap. This page documents what the parser accepts today.

1. Your first ecomap

The smallest useful ecomap: one center and three outside systems.

Four rules cover 80% of usage:

1. Start with the keyword ecomap, optionally followed by a quoted title.
2. Declare the center on its own line: center: id [label: "…"]. Exactly one center per diagram.
3. Declare each outside system on its own line: id [label: "…", category: …].
4. Connect any two declared IDs with a connection operator — === (strong), --- (normal), <-> (reciprocal), etc. See §3 for the full table. A trailing [label: "…"] adds an edge label.

Comments must be on their own line, starting with #, //, or Mermaid-style %%. Inline trailing comments will break the parser.

2. Center and outside systems

Every ecomap has one center and any number of outside systems. Both use the same id [attrs] syntax; the only difference is the center: prefix.

ID rules. Must match [a-zA-Z][a-zA-Z0-9_-]*. IDs are case-insensitive; the original token is kept as the default label.

Attributes accepted by the parser today:

2.1 System categories

Categories color-code outside systems by the life domain they belong to. The parser accepts any string — these are the values the renderer has themed palettes for:

3. Connections

A connection is one line: fromId OP toId optionally followed by [label: "…"]. Both IDs must already be declared (center counts).

3.1 Relationship-quality operators

3.2 Energy-flow operators

Layer arrow direction onto strong or normal lines:

The parser normalizes direction so arrows read relative to the center. Writing family === resettlement and resettlement === family produces the same diagram; writing clinic --> family vs family <-- clinic likewise produces the same arrow pointing from the clinic to the family.

3.3 Edge labels

A trailing [label: "…"] is the only attribute a connection line accepts. Put schedule, nature, or a short note here:

family === temple [label: "weekly service"]
clinic --> family [label: "vaccinations"]
caseworker <-> family [label: "every Tuesday"]

4. Labels & comments

• Title: ecomap "Nguyen Family" — first line only.
• Node label override: family [label: "The Nguyens"].
• Edge label: trailing [label: "…"] on a connection line.
• Mode suffix: ecomap:strengths "Smith family" is accepted. The suffix is stored as metadata.mode; current renderers ignore it.
• Comments: #, //, or %% at the start of a line (after leading whitespace). Inline trailing comments are not supported.

ecomap "Marcus Intake"
  # caseworker's notes — fine
  // also fine
  %% Mermaid-style comments are fine
  mom [category: family]   # ← THIS trailing comment breaks the parser

5. Reserved words & escaping

Reserved at line start: ecomap, center:.

Reserved operator tokens inside a line — avoid using these sequences in IDs: ===, ==, ---, - -, ~~~, ~=~, ~x~, -/-, and the directional variants listed in §3.2.

Strings with spaces must be double-quoted: titles and any label. Single quotes and backticks are not recognized.

6. Common mistakes

Real parser errors, what triggers them, and how to fix.

7. Grammar (EBNF)

document       = header (blank | comment | center | system | connection)*

header         = "ecomap" ( ":" mode )? ( WS quoted-string )? NEWLINE
mode           = [A-Za-z] [A-Za-z0-9_-]*
quoted-string  = '"' any-char-but-quote* '"'

center         = "center:" WS id ( "[" attrs "]" )? NEWLINE
system         = id ( "[" attrs "]" )? NEWLINE
connection     = id WS op WS id ( WS "[" "label:" quoted-string "]" )? NEWLINE

op             = "===" | "==" | "---" | "- -" | "~~~" | "~=~" | "~x~" | "-/-"
               | "===>" | "<===" | "<=>" | "==>" | "<=="
               | "-->" | "<--" | "<->"

id             = [a-zA-Z] [a-zA-Z0-9_-]*
attrs          = attr ("," attr)*
attr           = "label" ":" quoted-string
               | "category" ":" category
               | "size" ":" ("small" | "medium" | "large")
               | "importance" ":" ("major" | "moderate" | "minor")
               | "sector" ":" ("top" | "right" | "bottom" | "left")
               | "age" ":" digits
               | "male" | "female" | "unknown"
               | key ":" value                  // custom, stored as metadata

category       = "family" | "friends" | "work" | "education" | "health"
               | "mental-health" | "religion" | "recreation" | "legal"
               | "government" | "financial" | "community" | "cultural"
               | "substance" | "technology" | "pet" | "other"

comment        = ( "#" | "//" | "%%" ) any NEWLINE

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

8. Standard compliance

Schematex ecomaps follow Hartman (1978), Diagrammatic Assessment of Family Relationships for the core notation: a bounded center surrounded by outside systems, connecting lines that encode both quality and directionality. The category palette and the expanded operator set (stressful-strong, reciprocal arrows) follow conventions from contemporary clinical social work and nursing research.

What is implemented today:

• ✅ Center + outside-system radial structure
• ✅ 8 quality operators (strong / moderate / normal / weak / stressful / stressful-strong / conflictual / broken)
• ✅ 8 directional operators (one-way and reciprocal, at three intensities)
• ✅ Category color-coding (17 categories)
• ✅ Edge labels
• ⏳ Embedded mini-genogram as the center (see §10)
• ⏳ Sector-based layout hints beyond the current four cardinals

References:

• Hartman, A. (1978). Diagrammatic assessment of family relationships. Social Casework, 59(8), 465–476.
• Ray, R.A. & Street, A.F. (2005). Ecomapping: An innovative research tool for nurses. Journal of Advanced Nursing, 50(5), 545–552.
• Rempel, G.R., Neufeld, A., & Kushner, K.E. (2007). Interactive use of genograms and ecomaps in family caregiving research. Journal of Family Nursing, 13(4), 403–419.

9. Related examples

Ready-to-use scenarios from the examples gallery:

10. Roadmap

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

• Embedded mini-genogram as the center — declaring a full family block inside the center: node (indented couples and children) so the center is a small genogram rather than a single shape. The parser currently reads indented content under center: as skipped lines.
• Per-category default arrow semantics — e.g. auto-directional arrows for health systems (in) vs work systems (out).
• Multiple centers — ecomaps for two clients sharing some systems.
• Custom color overrides — [color: "#…"] on a system or connection.

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