> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lionlang.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Lion schemas: Effect Schema definitions

> All Effect Schema definitions exported by @lionlang/core — expression types, special form schemas, primitives, and the callable value schema.

Lion uses [Effect Schema](https://effect.website/docs/schema/introduction) throughout the evaluator to validate inputs, discriminate expression shapes at runtime, and produce typed parse errors. Each schema corresponds to a distinct concept in the Lion expression model and is exported from its own subpath so you can import only what you need.

## `@lionlang/core/schemas/lion-expression`

The core expression schemas describe the full range of values a Lion program can contain.

```typescript theme={null}
import {
  LionExpressionSchema,
  LionArrayExpressionSchema,
  LionRecordExpressionSchema,
} from "@lionlang/core/schemas/lion-expression";
import type { AssumedExpressionType } from "@lionlang/core/schemas/lion-expression";
```

<ResponseField name="LionExpressionSchema" type="Schema">
  The top-level union schema. Accepts any value that is a JSON primitive, an
  array of Lion expressions, or a record with string keys and Lion expression
  values. This is the schema used by `run` to validate the `expression`
  parameter before evaluation.

  ```typescript theme={null}
  Schema.Union(JsonPrimitiveSchema, LionArrayExpressionSchema, LionRecordExpressionSchema)
  ```
</ResponseField>

<ResponseField name="LionArrayExpressionSchema" type="Schema">
  A `Schema.Array` of recursively-suspended `LionExpressionSchema` elements.
  Used by `evaluate` to detect array expressions and dispatch them to
  `evaluateArray`.
</ResponseField>

<ResponseField name="LionRecordExpressionSchema" type="Schema">
  A `Schema.Record` where:

  * **Keys** must be non-empty strings (`minLength(1)`) and must not equal
    `"__proto__"`.
  * **Values** are recursively-suspended `LionExpressionSchema` elements.

  Used by `evaluate` to detect record expressions and dispatch them to
  `evaluateRecord`.
</ResponseField>

<ResponseField name="AssumedExpressionType" type="type alias">
  A recursive TypeScript type alias representing the structural form of a Lion
  expression before schema decoding:

  ```typescript theme={null}
  type AssumedExpressionType =
    | JsonPrimitiveType
    | readonly AssumedExpressionType[]
    | { readonly [key: string]: AssumedExpressionType };
  ```

  Used as the element type for the lazy `Schema.suspend` references inside the
  array and record schemas.
</ResponseField>

### Runtime type checking

Use `Schema.is` to narrow a value to a specific expression shape at runtime without throwing on failure:

```typescript theme={null}
import { Schema } from "effect";
import {
  LionExpressionSchema,
  LionArrayExpressionSchema,
  LionRecordExpressionSchema,
} from "@lionlang/core/schemas/lion-expression";

Schema.is(LionExpressionSchema)(value);       // value is LionExpressionType
Schema.is(LionArrayExpressionSchema)(value);  // value is LionArrayExpressionType
Schema.is(LionRecordExpressionSchema)(value); // value is LionRecordExpressionType
```

***

## `@lionlang/core/schemas/json-primitive`

```typescript theme={null}
import { JsonPrimitiveSchema } from "@lionlang/core/schemas/json-primitive";
import type { JsonPrimitiveType } from "@lionlang/core/schemas/json-primitive";
```

<ResponseField name="JsonPrimitiveSchema" type="Schema">
  A union of `Schema.String`, `Schema.Number`, `Schema.Boolean`, and
  `Schema.Null`. Represents the leaf values of a Lion expression tree.
  Numbers, booleans, and `null` evaluate to themselves; strings are resolved
  as environment references.
</ResponseField>

***

## `@lionlang/core/schemas/environment`

```typescript theme={null}
import type { Environment } from "@lionlang/core/schemas/environment";
```

<ResponseField name="Environment" type="type alias">
  The union type of `ToplevelEnvironment` and `InnerEnvironment`. Both carry a
  `bindingsRef: Ref<Record<string, unknown>>` for mutable name storage.
  `InnerEnvironment` additionally holds a `parent: Environment` reference for
  lexical scope lookup.

  You do not typically construct `Environment` values directly — use
  `makeEnvironment` from `@lionlang/core/evaluation/environment` instead.
</ResponseField>

***

## `@lionlang/core/schemas/evaluation`

Special form schemas and the callable value schema. Import what you need:

```typescript theme={null}
import {
  BeginFormSchema,
  CondFormSchema,
  DefineFormSchema,
  EvalFormSchema,
  FunctionCallFormSchema,
  LambdaFormSchema,
  MatchFormSchema,
  QuoteFormSchema,
  LionFunctionValueSchema,
} from "@lionlang/core/schemas/evaluation";
```

<ResponseField name="EvalFormSchema" type="Schema">
  `["eval", LionExpression]` — evaluates its argument, then evaluates the result.
</ResponseField>

<ResponseField name="QuoteFormSchema" type="Schema">
  `["quote", LionExpression]` — returns its argument unevaluated.
</ResponseField>

<ResponseField name="BeginFormSchema" type="Schema">
  `["begin", ...LionExpression[]]` — evaluates a sequence of expressions and returns the last value.
</ResponseField>

<ResponseField name="DefineFormSchema" type="Schema">
  `["define", ValidIdentifier, LionExpression]` — evaluates the expression and stores it in the global environment under `ValidIdentifier`. The identifier must be non-empty and cannot be one of the reserved keywords (`begin`, `define`, `eval`, `quote`, `lambda`, `cond`, `match`) or `__proto__`.
</ResponseField>

<ResponseField name="LambdaFormSchema" type="Schema">
  `["lambda", ValidIdentifier[], LionExpression]` — creates a closure over the current scope.
</ResponseField>

<ResponseField name="CondFormSchema" type="Schema">
  Union of `CondFormWithoutElseSchema` and `CondFormWithElseSchema`:

  ```
  ["cond", [predicate, result], ..., ["else", result]]
  ```

  The `else` branch is optional. Returns `null` when no branch matches and no `else` is present.
</ResponseField>

<ResponseField name="MatchFormSchema" type="Schema">
  ```
  ["match", value, [predicate, handler], ..., fallback-fn]
  ```

  Matches a value against predicate/handler pairs; the last element is a fallback function applied when no pattern matches.
</ResponseField>

<ResponseField name="FunctionCallFormSchema" type="Schema">
  `[LionExpression, ...LionExpression[]]` — a non-empty tuple where the head evaluates to a callable. Used as the final catch-all in `evaluateArray` after all special forms have been checked.
</ResponseField>

<ResponseField name="LionFunctionValueSchema" type="Schema">
  A declared schema that matches any JavaScript `function`. Used to validate that the head of a function call expression is actually callable:

  ```typescript theme={null}
  export type LionFunctionValueType = (...args: unknown[]) => EvaluateResult;
  ```
</ResponseField>