@antelopejs/interface-data-api 0.4.0 → 0.6.0

package/docs/4.access-rights.md

@@ -1,43 +1,47 @@
-# Access Rights
+---
+title: Access rights
+description: The @Access decorator, the three AccessMode values and per-action overrides that decide which fields each route reads and writes.
+mode: reference
+---
 
 ## Overview
 
-The `@Access` decorator controls how fields are read and written through the API. Each field can be set to read-only, write-only, or read-write, providing fine-grained control over data exposure. Access modes can also be overridden on a per-action basis, allowing different permissions for `get`, `list`, `new`, and `edit` operations.
+The `@Access` decorator sets how the API reads and writes a field. A field is read-only, write-only or read-write. An override can give one action (`get`, `list`, `new` or `edit`) a different mode.
 
 ## Separate field policy from caller permissions
 
-`@Access` answers “may this action read or write this field?”, not “may this user access this record?”. Authenticate the caller and apply record-level policy separately. A write-only password is hidden from responses, but this decorator does not hash it.
+`@Access` answers "may this action read or write this field?". It does not answer "may this user access this record?". Authenticate the caller and apply record-level policy separately. A write-only password stays out of responses, but `@Access` does not hash it.
 
-Build the field policy in this order:
+Build the field policy in this order.
 
-1. Set `@Access` for each public field. Undecorated fields remain private.
-2. Add action overrides for differences between creation and editing.
-3. Add `@Listable` for the fields selected by list responses; readable alone does not define a list projection.
+1. Set `@Access` on each public field. A field without it stays private.
+2. Add action overrides where creation and editing differ.
+3. Add `@Listable` to the fields list responses select. Read access alone does not put a field in a list response.
 4. Add validators and mandatory-field rules for writable inputs.
 
-For example, a display name can be readable and writable, an ID readable only, and a password writable only. Test each direction: attempting to write a read-only field is ignored, while omitting a mandatory writable field is a validation concern.
+For example, a display name is readable and writable, an ID is read-only, and a password is write-only. Test each direction. The routes ignore a value sent for a read-only field. A missing mandatory field is a validation error, covered on the [validators page](./5.validators.md).
 
-## Access Modes
+## Access modes
 
-The `AccessMode` enum defines three permission levels:
+The `AccessMode` enum defines three modes.
 
 ```typescript
 import { Access, AccessMode } from "@antelopejs/interface-data-api/metadata";
 ```
 
-| Mode                   | Value | Description                                                                                         |
-| ---------------------- | ----- | --------------------------------------------------------------------------------------------------- |
-| `AccessMode.ReadOnly`  | `1`   | Field is readable; list responses also require selection by the pluck mode. POST and PUT ignore it. |
-| `AccessMode.WriteOnly` | `2`   | Field is accepted in POST and PUT bodies but never appears in responses                             |
-| `AccessMode.ReadWrite` | `3`   | Field is both readable and writable                                                                 |
+| Mode                   | Value | Description                                                                                            |
+| ---------------------- | ----- | ------------------------------------------------------------------------------------------------------ |
+| `AccessMode.ReadOnly`  | `1`   | The field is readable. A list response also needs the pluck mode to select it. POST and PUT ignore it. |
+| `AccessMode.WriteOnly` | `2`   | POST and PUT bodies accept the field, and no response holds it                                         |
+| `AccessMode.ReadWrite` | `3`   | The field is readable and writable                                                                     |
 
-## Basic Usage
+## Basic usage
 
-### Read-Only Fields
+### Read-only fields
 
-Read-only fields appear in API responses but cannot be modified through create or update requests. Values sent for these fields in request bodies are silently ignored.
+A read-only field appears in responses, and create and update requests cannot change it. The routes ignore a value sent for it in a request body and report nothing.
 
-```typescript
+```typescript fragment
 @RegisterDataController()
 class UserAPI extends DataController(
   User,
@@ -59,13 +63,13 @@ class UserAPI extends DataController(
 }
 ```
 
-A PUT request to `/users/edit?id=user-123` with `{ "createdAt": "2025-01-01", "name": "Alice" }` updates only `name`. The `createdAt` field is ignored.
+A PUT request to `/users/edit?id=user-123` with `{ "createdAt": "2025-01-01", "name": "Alice" }` updates only `name`. The route ignores `createdAt`.
 
-### Write-Only Fields
+### Write-only fields
 
-Write-only fields accept input during create and update operations but are never included in API responses. This is useful for sensitive data like passwords.
+A write-only field accepts input on create and update, and no response holds it. Passwords and other secrets use this mode.
 
-```typescript
+```typescript fragment
 @RegisterDataController()
 class UserAPI extends DataController(
   User,
@@ -87,7 +91,7 @@ class UserAPI extends DataController(
 }
 ```
 
-A GET request to `/users/get?id=user-123` returns `name` and `email` but never includes `password`:
+A GET request to `/users/get?id=user-123` returns `name` and `email`, and never `password`.
 
 ```json
 {
@@ -96,11 +100,11 @@ A GET request to `/users/get?id=user-123` returns `name` and `email` but never i
 }
 ```
 
-### Read-Write Fields
+### Read-write fields
 
-Read-write fields are fully accessible: they appear in responses and accept input in request bodies.
+A read-write field appears in responses and accepts input in request bodies.
 
-```typescript
+```typescript fragment
 @Access(AccessMode.ReadWrite)
 declare email: string;
 
@@ -108,21 +112,21 @@ declare email: string;
 declare name: string;
 ```
 
-## Per-Action Overrides
+## Per-action overrides
 
-The `@Access` decorator accepts an optional second argument to override the access mode for specific actions. This allows a field to behave differently depending on the operation being performed.
+`@Access` takes an optional second argument that overrides the mode for named actions.
 
-```typescript
-@Access(defaultMode: AccessMode, overrides?: Record<string, AccessMode>)
+```typescript fragment
+@Access(mode: AccessMode, overrides?: Record<string, AccessMode>)
 ```
 
-The `overrides` object maps action names (`"get"`, `"list"`, `"new"`, `"edit"`) to an `AccessMode` value. Actions not listed in the overrides use the default mode.
+The `overrides` object maps action names (`"get"`, `"list"`, `"new"` and `"edit"`) to an `AccessMode`. An action that `overrides` does not name uses `mode`.
 
-To read the access a field has in one action, outside the routes (to render a form read-only on edit, for example), call `GetEffectiveMode(field, action)` from `@antelopejs/interface-data-api/metadata` with the field's metadata (`meta.fields[name]`). It is the mode the routes apply.
+To read the mode a field has in one action outside the routes (to render a form read-only on edit, for example), call `GetEffectiveMode(field, action)` from `@antelopejs/interface-data-api/metadata` with the field's metadata (`meta.fields[name]`). It returns the mode the routes apply.
 
-### Example: Writable on Create, Read-Only on Edit
+### Example: writable on create, read-only on edit
 
-```typescript
+```typescript fragment
 @RegisterDataController()
 class UserAPI extends DataController(
   User,
@@ -139,25 +143,25 @@ class UserAPI extends DataController(
   @Access(AccessMode.ReadWrite)
   declare name: string;
 
-  // role can be set when creating, but cannot be changed during edit
+  // Writable on new, read-only on edit
   @Access(AccessMode.ReadWrite, { edit: AccessMode.ReadOnly })
   declare role: string;
 
-  // age is read-only by default, but writable during creation
+  // Read-only, except on new
   @Access(AccessMode.ReadOnly, { new: AccessMode.ReadWrite })
   declare age: number;
 }
 ```
 
-In this configuration:
+With this configuration:
 
-- `role` is readable and writable in all operations except `edit`, where it becomes read-only.
-- `age` is read-only by default but can be set during `new` (create) operations.
+- `role` is readable and writable in every action except `edit`, where it is read-only.
+- `age` is read-only, except in `new`, where a create request can set it.
 
-## Fields Without `@Access`
+## Fields without `@Access`
 
-Ordinary fields need `@Access` to appear in responses or accept input; `@Listable` alone does not grant access. The derived-field decorators [`@Joined`](./10.joined.md) and [`@Computed`](./11.computed.md) are exceptions: they set read-only access themselves.
+An ordinary field needs `@Access` to appear in responses or accept input. `@Listable` alone grants no access. The derived-field decorators [`@Joined`](./10.joined.md) and [`@Computed`](./11.computed.md) are the exceptions. They set read-only access themselves.
 
-## Next Steps
+## Next steps
 
-See the [validators documentation](./5.validators.md) to learn how to enforce validation rules on field values.
+The [validators page](./5.validators.md) covers validation rules on field values.

package/docs/5.validators.md

@@ -1,16 +1,22 @@
-# Validators
+---
+title: Validators
+description: The @Validator, @Mandatory and @Optional decorators, the checks they run on create and update, and the 400 bodies they answer.
+mode: reference
+---
 
 ## Overview
 
-Validators provide field-level data integrity checks that run automatically during create and update operations. The `@Validator` decorator attaches a custom validation function to a field, while `@Mandatory` ensures that specific fields are present in request bodies for given operations. The `@Optional` decorator explicitly marks a field as not mandatory.
+Validators check field values on the `new` and `edit` routes. `@Validator` attaches a validation function to a field. `@Mandatory` requires a field in the request body for the named operations. `@Optional` marks a field as mandatory for no operation.
 
-## The `@Validator` Decorator
+The routes parse the body, then run the mandatory check, then the validators. A failed mandatory check answers `400` before any validator runs.
 
-### Basic Usage
+## The `@Validator` decorator
 
-The `@Validator` decorator accepts a function that receives the field value and returns `true` if valid or `false` if invalid. It can instead return a parse result (see [Parsed Values](#parsed-values)) so that the parsed value is written. The function can also return a `Promise` of either for asynchronous validation.
+### Basic usage
 
-```typescript
+`@Validator` takes a function that receives the field value and returns `true` for a valid value or `false` for an invalid one. It can return a parse result instead (see [parsed values](#parsed-values)), and the route then writes the parsed value. For asynchronous validation, the function returns a `Promise` of either.
+
+```typescript fragment
 import { Validator } from "@antelopejs/interface-data-api/metadata";
 
 @RegisterDataController()
@@ -33,30 +39,40 @@ class UserAPI extends DataController(
 }
 ```
 
-### Validation Function Signature
+### Validation function signature
 
 ```typescript
+type FieldValue =
+  string | number | boolean | null | Date | FieldValue[] | FieldValues;
+
+interface FieldValues {
+  [field: string]: FieldValue | undefined;
+}
+
 type FieldValidator = (
-  value: unknown,
+  value: FieldValue | undefined,
 ) => FieldValidationResult | Promise<FieldValidationResult>;
 
 type FieldValidationResult =
-  boolean | { success: true; data: unknown } | { success: false };
+  | boolean
+  | { success: true; data: FieldValue | undefined }
+  | { success: false };
 ```
 
-The function:
+The function behaves as follows.
 
-- Receives the raw field value from the request body.
-- Returns `true` when the value is valid: the raw value is written.
-- Returns `{ success: true, data }` when the value is valid: `data` is written instead of the raw value.
-- Returns `false` or `{ success: false }` when the value is invalid, which triggers a `400 Bad Request` response.
-- Should handle unexpected types gracefully (e.g., check `typeof` before accessing properties).
+- It runs only for a field present in the request body.
+- It receives the raw field value from the request body. The value is JSON, or a `Date` or `undefined` when a route that wraps `new` or `edit` amended the parsed body. Narrow `FieldValue | undefined` before you use it.
+- It returns `true` for a valid value, and the route writes the raw value.
+- It returns `{ success: true, data }` for a valid value, and the route writes `data` instead of the raw value.
+- It returns `false` or `{ success: false }` for an invalid value, and the route answers `400 Bad Request`.
+- It receives any JSON type, so check the type with `typeof` before you read a property.
 
-### Parsed Values
+### Parsed values
 
-A validator returning a parse result writes the parsed value on both `new` and `edit`. The result has the shape of zod's `safeParse`, so a zod schema can be used directly:
+When a validator returns a parse result, the route writes the parsed value on both `new` and `edit`. The result has the shape of the result of zod's `safeParse`, so a zod schema works as a validator.
 
-```typescript
+```typescript fragment
 const startsAtSchema = z.coerce.date();
 
 @Access(AccessMode.ReadWrite)
@@ -64,11 +80,11 @@ const startsAtSchema = z.coerce.date();
 declare startsAt: Date; // "2026-01-15" is stored as a Date
 ```
 
-## Common Validation Patterns
+## Common validation patterns
 
-### String Validation
+### String validation
 
-```typescript
+```typescript fragment
 // Minimum length
 @Validator((value) => typeof value === "string" && value.length >= 2)
 declare firstName: string;
@@ -84,9 +100,9 @@ const VALID_ROLES = ["admin", "editor", "viewer"];
 declare role: string;
 ```
 
-### Number Validation
+### Number validation
 
-```typescript
+```typescript fragment
 // Range
 @Validator((value) => typeof value === "number" && value >= 0 && value <= 120)
 declare age: number;
@@ -100,9 +116,9 @@ declare quantity: number;
 declare price: number;
 ```
 
-### Date Validation
+### Date validation
 
-```typescript
+```typescript fragment
 // Valid date string
 @Validator((value) => typeof value === "string" && !isNaN(Date.parse(value)))
 declare birthDate: string;
@@ -116,11 +132,11 @@ declare birthDate: string;
 declare appointmentDate: string;
 ```
 
-### Async Validation
+### Async validation
 
-An asynchronous lookup can give early feedback, but a check followed by an insert is not a uniqueness guarantee: concurrent requests can both pass. Enforce uniqueness in the database where supported, and handle write conflicts. `lookupByEmail` below is an application-supplied function.
+An asynchronous lookup gives early feedback. A check followed by an insert does not guarantee uniqueness, because two concurrent requests can both pass the check. Enforce uniqueness in the database where the database supports it, and handle write conflicts. `lookupByEmail` below is a function your application supplies.
 
-```typescript
+```typescript fragment
 // Check uniqueness against the database
 @Validator(async (value) => {
   if (typeof value !== "string") return false;
@@ -130,12 +146,12 @@ An asynchronous lookup can give early feedback, but a check followed by an inser
 declare email: string;
 ```
 
-## The `@Mandatory` Decorator
+## The `@Mandatory` decorator
 
-The `@Mandatory` decorator specifies which operations require a field in the request body. Unlike `@Validator`, which checks field content, `@Mandatory` only verifies that the field is provided:
+`@Mandatory` names the operations that require a field in the request body. `@Validator` checks the content of a field. `@Mandatory` checks only that the body provides it.
 
-- On `"edit"`, the body only carries the fields to update: a mandatory field absent from the body keeps its stored value and is accepted, while a mandatory field cleared by the body (`null`, `""` or `[]`) is rejected.
-- On any other operation (such as `"new"`), a mandatory field must be present in the body.
+- On `"edit"`, the body carries only the fields to update. The route accepts a mandatory field absent from the body, which keeps its stored value. It rejects a mandatory field that the body clears with `null`, `""` or `[]`.
+- On any other operation, such as `"new"`, the body must hold every mandatory field.
 
 ```typescript
 import { Mandatory } from "@antelopejs/interface-data-api/metadata";
@@ -143,9 +159,9 @@ import { Mandatory } from "@antelopejs/interface-data-api/metadata";
 
 ### Usage
 
-Pass one or more operation names as arguments. Common operation names are `"new"` (create) and `"edit"` (update).
+Pass one or more operation names as arguments. The default routes check `"new"` (create) and `"edit"` (update).
 
-```typescript
+```typescript fragment
 @RegisterDataController()
 class UserAPI extends DataController(
   User,
@@ -180,11 +196,11 @@ In this example:
 - `status` cannot be cleared when editing an existing record.
 - `notes` is always optional.
 
-### Skip Mandatory Validation
+### Skip mandatory validation
 
-Use `DefaultRoutes.WithOptions` with the `noMandatory` option to create an endpoint that skips mandatory field checks.
+`DefaultRoutes.WithOptions` with the `noMandatory` option creates an endpoint that skips the mandatory field check. Any non-empty string turns the option on. The validators still run.
 
-```typescript
+```typescript fragment
 const routes = {
   edit: DefaultRoutes.Edit,
   patchEdit: DefaultRoutes.WithOptions(DefaultRoutes.Edit, {
@@ -202,26 +218,28 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 
 Requests to `/users/edit` cannot clear `status`, while requests to `/users/patchEdit` can.
 
-## The `@Optional` Decorator
+## The `@Optional` decorator
 
-The `@Optional` decorator explicitly marks a field as not mandatory for any operation. Use it on fields that have no other decorators but still need to be recognized by the Data API metadata system.
+`@Optional` marks a field as mandatory for no operation, and records the field in the Data API metadata. Use it only on a field with no other decorator, since it clears what `@Mandatory` set.
 
-```typescript
+```typescript fragment
 import { Optional } from "@antelopejs/interface-data-api/metadata";
 
 @Optional()
 declare notes: string;
 ```
 
-## Error Handling
+## Error handling
 
-When validation or mandatory checks fail, the API returns a `400 Bad Request` response whose JSON body names what went wrong and the fields concerned, for the client to word it and show it under each field:
+When a mandatory check or a validator fails, the route answers `400 Bad Request`. The JSON body holds a `code` for what went wrong and the `fields` concerned, so the client can word the error and show it under each field.
 
-- **Mandatory failure:** `{ "code": "missing_mandatory_fields", "fields": ["email", "password"] }`
-- **Validator failure:** `{ "code": "invalid_field_types", "fields": ["age", "email"] }`
+| Failure   | Body                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| Mandatory | `{ "code": "missing_mandatory_fields", "fields": ["email", "password"] }` |
+| Validator | `{ "code": "invalid_field_types", "fields": ["age", "email"] }`           |
 
-The codes are exported as `Validation.MISSING_MANDATORY_FIELDS` and `Validation.INVALID_FIELD_TYPES` (`@antelopejs/interface-data-api/components`), the body's type as `Validation.FieldsErrorBody`. All fields are checked: `fields` lists every one that failed.
+`@antelopejs/interface-data-api/components` exports the codes as `Validation.MISSING_MANDATORY_FIELDS` and `Validation.INVALID_FIELD_TYPES`, and the body type as `Validation.FieldsErrorBody`. Each check covers every field, and `fields` lists every field that failed it.
 
-## Next Steps
+## Next steps
 
-See the [listable fields documentation](./6.listable.md) to learn how to control field visibility in list operations and configure pagination.
+The [listable fields page](./6.listable.md) covers which fields list responses hold and how pagination works.

package/docs/6.listable.md

@@ -1,16 +1,20 @@
-# Listable Fields
+---
+title: Listable fields
+description: Choose the fields a list route returns with @Listable, serve several field sets with pluck modes, page the results, and sort them with @Sortable.
+mode: reference
+---
 
 ## Overview
 
-The `@Listable` decorator controls which fields are included in list endpoint responses. By default, list operations only return fields explicitly marked as listable, keeping payloads lightweight. The decorator supports multiple pluck modes for different levels of detail, and list responses include built-in pagination metadata.
+The `@Listable` decorator selects the fields that list responses include. A list route returns only the fields marked as listable, so list payloads stay small. Pluck modes let one controller serve several field sets, and every list response carries pagination metadata.
 
-The `@Sortable` decorator marks fields that can be used as a sorting key in list queries.
+The `@Sortable` decorator marks the fields that a list request can sort on.
 
-## Basic Usage
+## Basic usage
 
-Fields decorated with `@Listable()` are included in list responses. Fields without this decorator are excluded from list results but still appear in single-record `get` responses (provided they have read access).
+A list response includes the fields decorated with `@Listable()`. A field without the decorator is left out of list results, but a single-record `get` response still includes it when the field has read access.
 
-```typescript
+```typescript fragment
 import {
   Access,
   AccessMode,
@@ -43,24 +47,24 @@ class UserAPI extends DataController(
 
 A request to `GET /users/list` returns `_id` and `email` for each record. A request to `GET /users/get?id=user-123` returns all three fields.
 
-## Pluck Modes
+## Pluck modes
 
-Pluck modes allow a single controller to serve multiple list views with different field selections. Each `@Listable` call can target a named mode.
+A pluck mode is a named field set. With pluck modes, one controller serves several list views, each with its own fields. Each `@Listable` call adds the field to one mode.
 
-### Default Mode
+### Default mode
 
-Calling `@Listable()` without a mode name registers the field under the default `"list"` mode.
+`@Listable()` without a mode name adds the field to the default `"list"` mode.
 
-```typescript
+```typescript fragment
 @Listable()
 declare name: string;
 ```
 
-### Custom Modes
+### Custom modes
 
-Pass `true` and a mode name to register a field under a specific pluck mode.
+`@Listable(true, "detailed")` adds the field to the `"detailed"` mode.
 
-```typescript
+```typescript fragment
 @Listable()                    // Included in default "list" mode
 @Listable(true, "detailed")   // Also included in "detailed" mode
 declare name: string;
@@ -72,21 +76,21 @@ declare internalNotes: string;
 declare email: string;
 ```
 
-### Exclude from a Mode
+### Exclude from a mode
 
-Pass `false` to explicitly exclude a field from a mode.
+`@Listable(false, "minimal")` leaves the field out of the `"minimal"` mode.
 
-```typescript
+```typescript fragment
 @Listable()
 @Listable(false, "minimal")   // Excluded from "minimal" mode
 declare description: string;
 ```
 
-### Access Pluck Modes via Routes
+### Access pluck modes via routes
 
-Define separate routes for each pluck mode using `DefaultRoutes.WithOptions` with the `pluckMode` option.
+Each pluck mode needs its own route. `DefaultRoutes.WithOptions` sets the route's `pluckMode` option.
 
-```typescript
+```typescript fragment
 const routes = {
   list: DefaultRoutes.List,
   detailed: DefaultRoutes.WithOptions(DefaultRoutes.List, {
@@ -114,13 +118,13 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 - `GET /users/list` returns only `name`.
 - `GET /users/detailed` returns both `name` and `internalNotes`.
 
-Modes are independent field sets: `"detailed"` does not inherit `"list"`. The example includes `name` in both modes explicitly. A registered list route whose `pluckMode` has never been declared returns `400 Bad Request` unless `noPluck` is enabled; an unregistered URL instead returns `404`.
+Modes are independent field sets. The `"detailed"` mode does not inherit the fields of `"list"`, so the example adds `name` to both modes. A registered list route whose `pluckMode` no field declares returns `400 Bad Request`, unless the route sets `noPluck`. A URL that matches no route returns `404`.
 
-### Listable with Getters
+### Listable with getters
 
-When a field uses a getter (computed property), the `@Listable` decorator must specify which database fields the getter depends on. This ensures those fields are fetched from the database.
+A getter (computed property) reads fields that the database must return. Its `@Listable` decorator lists those database fields, so the list query fetches them.
 
-```typescript
+```typescript fragment
 @Listable(["firstName", "lastName"])
 @Access(AccessMode.ReadOnly)
 get fullName() {
@@ -130,9 +134,9 @@ get fullName() {
 
 ## Pagination
 
-List responses include pagination metadata. The response structure is:
+Every list response carries pagination metadata. The response has this shape:
 
-```typescript
+```typescript fragment
 {
   results: T[];     // Records for the current page
   total: number;    // Total number of matching records
@@ -141,12 +145,12 @@ List responses include pagination metadata. The response structure is:
 }
 ```
 
-### Query Parameters
+### Query parameters
 
-| Parameter | Default | Description                         |
-| --------- | ------- | ----------------------------------- |
-| `limit`   | `10`    | Maximum number of records to return |
-| `offset`  | `0`     | Number of records to skip           |
+| Parameter | Default                                          | Description                         |
+| --------- | ------------------------------------------------ | ----------------------------------- |
+| `limit`   | The route's `maxPage`, or `10` when it sets none | Maximum number of records to return |
+| `offset`  | `0`                                              | Number of records to skip           |
 
 ### Example
 
@@ -166,11 +170,11 @@ GET /users/list?limit=2&offset=4
 }
 ```
 
-### Limit Maximum Page Size
+### Limit maximum page size
 
-Use the `maxPage` route option to cap the `limit` parameter. If a request specifies a `limit` larger than `maxPage`, the value is clamped to `maxPage`.
+The `maxPage` route option caps the `limit` parameter. A request whose `limit` is larger than `maxPage` gets `maxPage` records at most. A request without `limit` also gets `maxPage` records. A route without `maxPage` caps `limit` at `100`.
 
-```typescript
+```typescript fragment
 const routes = {
   list: DefaultRoutes.WithOptions(DefaultRoutes.List, { maxPage: 25 }),
 };
@@ -183,9 +187,9 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 
 ## Sorting with `@Sortable`
 
-The `@Sortable` decorator marks a field as eligible for use as a sorting key in list operations.
+The `@Sortable` decorator lets a list request sort on the field.
 
-```typescript
+```typescript fragment
 import { Sortable } from "@antelopejs/interface-data-api/metadata";
 
 @RegisterDataController()
@@ -215,18 +219,18 @@ class UserAPI extends DataController(
 }
 ```
 
-### Sort Query Parameters
+### Sort query parameters
 
-| Parameter       | Description                                                        |
-| --------------- | ------------------------------------------------------------------ |
-| `sortKey`       | The field name to sort by. Must be decorated with `@Sortable`.     |
-| `sortDirection` | `"asc"` (ascending) or `"desc"` (descending). Defaults to `"asc"`. |
+| Parameter       | Description                                                                             |
+| --------------- | --------------------------------------------------------------------------------------- |
+| `sortKey`       | The field name to sort by. The field must have `@Sortable`.                             |
+| `sortDirection` | `"asc"` (ascending) or `"desc"` (descending). A missing or other value sorts ascending. |
 
-### The `noIndex` Option
+### The `noIndex` option
 
-By default, `@Sortable()` marks the field for indexed ordering. Set `noIndex: true` when it is not indexed. Both paths build an AQL `orderBy` operation; this option changes where sorting is staged, not whether rows are sorted in application memory. The provider determines how the database executes that ordering.
+By default, `@Sortable()` marks the field for indexed ordering. Set `noIndex: true` when the field has no index. Both settings build a database `orderBy` operation, and neither sorts rows in application memory. The option changes where the list query places the sort. The database provider decides how it runs the ordering.
 
-```typescript
+```typescript fragment
 @Sortable()                    // Uses database index for sorting
 declare _id: string;
 
@@ -234,9 +238,9 @@ declare _id: string;
 declare name: string;
 ```
 
-### Localized Fields
+### Localized fields
 
-A `@Localized` field is sorted on its value in the request's locale, the one the controller's `@ModifierKey(LocalizationModifier)` field holds. A row with no value in that locale, or an empty one, sorts on its `fallbackLocale` value. This ordering is computed per row, so it never uses an index, whatever `noIndex` says.
+A `@Localized` field sorts on its value in the request's locale, which the controller's `@ModifierKey(LocalizationModifier)` field holds. A row with no value in that locale, or an empty one, sorts on its `fallbackLocale` value. The list query computes this value for each row, so the sort never uses an index, whatever `noIndex` says.
 
 ### Example
 
@@ -257,8 +261,8 @@ GET /users/list?sortKey=age&sortDirection=desc&limit=3
 }
 ```
 
-If `sortKey` refers to a field that is not marked with `@Sortable`, the API returns a `400 Bad Request` error.
+If `sortKey` names a field without `@Sortable`, the API returns `400 Bad Request` with the message `Field is not sortable.`
 
-## Next Steps
+## Next steps
 
-See the [foreign keys documentation](./7.foreign-keys.md) to learn how to establish relationships between tables.
+To link records across tables, see [Foreign keys](./7.foreign-keys.md).