From 615502b1b07cd99cdc735cf42d2a46c3f84be75c Mon Sep 17 00:00:00 2001
From: sanmaxdev <sanmaxdev@users.noreply.github.com>
Date: Tue, 7 Jul 2026 07:06:32 +0000
Subject: [PATCH] docs: document typed map environments

---
 docs/environment.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/environment.md b/docs/environment.md
index 450e9e30c..e6e75c0c9 100644
--- a/docs/environment.md
+++ b/docs/environment.md
@@ -104,6 +104,30 @@ struct.unknown // error (unknown field)
 foobar         // error (unknown variable)
 ```
 
+Use [`types.Map`](https://pkg.go.dev/github.com/expr-lang/expr/types#Map) when the environment shape is only known at runtime, but you still want Expr to type check the available keys. The compiled program can then run against a regular `map[string]any` value with the same shape.
+
+```go
+envType := types.Map{
+    "user": types.Map{
+        "name": types.String,
+        "age":  types.Int,
+    },
+}
+
+program, err := expr.Compile(`user.name + " is " + string(user.age)`, expr.Env(envType))
+```
+
+`types.Map` is strict by default, so an unknown key such as `user.email` fails during compilation. Add [`types.Extra`](https://pkg.go.dev/github.com/expr-lang/expr/types#Extra) when a map should also allow additional keys of a known type.
+
+```go
+envType := types.Map{
+    "user": types.Map{
+        "name":      types.String,
+        types.Extra: types.Any,
+    },
+}
+```
+
 :::note
 The `foobar` variable is not defined in the environment.
 By default, Expr will return an error if unknown variables are used in the expression.