@nxgt/typespec 0.9.2 → 0.11.0

package/README.md

@@ -125,7 +125,7 @@ namespace Blog;
 @route("/posts")
 interface Posts {
   @get getPost(@path postId: string): Post | NotFound | Unauthorized;
-  @post createPost(@body post: Create<Post>): {
+  @post createPost(@body post: CreateRequest<Post>): {
     @statusCode _: 201;
     @body post: Post;
   } | BadRequest | Conflict | ErrorResponse<503>;
@@ -175,8 +175,9 @@ an alias leaves out:
 interface Users {
   @get list(...PageParameters): Page<User> | ListErrors;
   @get get(@path id: uuid): User | GetErrors;
-  @post create(@body user: User): User | CreateErrors | AuthErrors | TooManyRequests;
-  @patch update(@path id: uuid, @body user: User): User | UpdateErrors;
+  @post create(@body user: CreateRequest<User>): User | CreateErrors | AuthErrors | TooManyRequests;
+  @put update(@path id: uuid, @body user: UpdateRequest<User>): User | UpdateErrors;
+  @patch patch(@path id: uuid, @body user: PatchRequest<User>): User | UpdateErrors;
   @delete delete(@path id: uuid): NoContentResponse | DeleteErrors;
 }
 ```
@@ -184,6 +185,26 @@ interface Users {
 An alias is exactly its union, so the OpenAPI it emits is the same as
 writing the responses out.
 
+### Request bodies
+
+`CreateRequest<T>`, `UpdateRequest<T>` and `PatchRequest<T>` are TypeSpec's own
+`Create`, `Update` and `MergePatchUpdate`, named so the generated types and
+schemas read `CreatePostRequest`, `UpdatePostRequest` and `PatchPostRequest`:
+
+```tsp
+@post createPost(@body post: CreateRequest<Post>): {
+  @statusCode _: 201;
+  @body post: Post;
+} | BadRequest;
+@put updatePost(@path postId: uuid, @body post: UpdateRequest<Post>): Post | BadRequest | NotFound;
+@patch patchPost(@path postId: uuid, @body post: PatchRequest<Post>): Post | BadRequest | NotFound;
+```
+
+A `PUT` body keeps each property as optional as the model declares it; a
+`PATCH` body is a JSON Merge Patch, `application/merge-patch+json`, with
+every property optional. `Create<Post, "New{name}">` names a body your own
+way. See [Request bodies](docs/guide/requests.md).
+
 ### Pagination
 
 Spread the query of a page into the operation's parameters, and answer the
@@ -291,15 +312,34 @@ model Post {
 
 | Name | Emitted as | Generated | drizzle |
 | --- | --- | --- | --- |
-| `uuid` | the schema `Uuid`, `format: uuid` | `Uuid`, `z.guid()` | `id()` |
-| `email` | the schema `Email`, `format: email` | `Email`, `z.email()` | |
-| `...Timestamps` | `createdAt`, `updatedAt`, read-only | left out of `Create<T>` and updates | `timestamps()` |
+| `uuid` | the schema `UUID`, `format: uuid`, a pattern for versions 1–8 | `UUID`, `z.guid().regex(…)` | `id()` |
+| `email` | `emailAddress`, the schema `EmailAddress`, `format: email` | `EmailAddress`, `z.string().regex(…)` | |
+| `...Timestamps` | `createdAt`, `updatedAt`, read-only | left out of `CreateRequest<T>` and updates | `timestamps()` |
 | `...SoftDelete` | `deletedAt: utcDateTime \| null`, read-only | | `softDelete()` |
-| `...Versioned` | `version: integer`, read and update | kept in `MergePatchUpdate<T>` | `version()` |
+| `...Versioned` | `version: integer`, read and update | kept in `UpdateRequest<T>` and `PatchRequest<T>` | `version()` |
 | `...Actors<Id = uuid>` | `createdBy`, `updatedBy`, `deletedBy`, `Id \| null`, read-only | | `actors()` |
 
-TypeSpec's own `url` is the address of a page, `format: uri`, generated as
-`z.url()`. More in [Scalars and columns](docs/guide/columns.md).
+Every scalar of [`@nxgt/graphql-scalars`](https://www.npmjs.com/package/@nxgt/graphql-scalars)
+is declared too, as a camelCase scalar (`latitude`, `currency`, `positiveInt`,
+`httpUrl`, `ipV4`, `isoDuration`):
+
+```tsp
+model Place {
+  location: { latitude: latitude; longitude: longitude };
+  currency: currency;
+  openedOn: date;
+  homepage?: httpUrl;
+  seats: positiveInt;
+}
+```
+
+Each is an OpenAPI component named as in GraphQL (`Latitude`, `URL`), with a
+`format`, a pattern or bounds approximating the rule, and `x-nxgt-scalar`
+naming it. The exact rules (checksums, ISO and IANA lists) are outside the
+pattern. TypeSpec's own `url` takes any scheme; `httpUrl` takes `http:` and
+`https:`. Every scalar by category, in
+[Scalars](docs/guide/scalars.md); the ids, the addresses and the columns, in
+[Scalars and columns](docs/guide/columns.md).
 
 ### Headers
 
@@ -307,7 +347,7 @@ Spread the headers of an idempotent write and of a rate limit into an
 operation and its replies:
 
 ```tsp
-@post createPost(...IdempotencyKeyHeader, @body post: Create<Post>): {
+@post createPost(...IdempotencyKeyHeader, @body post: CreateRequest<Post>): {
   @statusCode _: 201;
   ...IdempotentReplayedHeader;
   ...RateLimitHeaders;
@@ -488,6 +528,9 @@ In the ruleset `@nxgt/typespec/recommended`; each is a warning, and named
 | `Page<Item>` | `{ items: Item[], total, page, pageSize, pageCount }`, the schema `<Item>Page` |
 | `CursorPageParameters` | the query `after` and `limit` |
 | `CursorPage<Item>` | `{ items: Item[], nextCursor: string \| null }`, the schema `<Item>CursorPage` |
+| `CreateRequest<T>` | `Create<T, "Create{name}Request">`: the body of a create, `CreatePostRequest` |
+| `UpdateRequest<T>` | `Update<T, "Update{name}Request">`: the body of a `PUT`, `UpdatePostRequest` |
+| `PatchRequest<T>` | `MergePatchUpdate<T, "Patch{name}Request">`: a merge patch, all optional, `PatchPostRequest` |
 | `ValidationIssue` | `{ target: ValidationTarget, path: (string \| integer)[], code: string, message: string }` |
 | `ValidationTarget` | `"param" \| "query" \| "header" \| "json" \| "form" \| "body" \| "response"` |
 
@@ -503,8 +546,18 @@ In the ruleset `@nxgt/typespec/recommended`; each is a warning, and named
 
 | Name | What it is |
 | --- | --- |
-| `uuid` | a string, `format: uuid`; the schema `Uuid` |
-| `email` | a string, `format: email`; the schema `Email` |
+| `uuid` | an RFC 9562 UUID, `format: uuid` and a pattern; the schema `UUID` |
+| `email` | an alias of `emailAddress`, `format: email` and a pattern; the schema `EmailAddress` |
+| `guid`, `uuidV4`, `uuidV7` | a UUID of any shape, of version 4, of version 7; `GUID`, `UUIDv4`, `UUIDv7` |
+| `ulid`, `cuid2`, `nanoId`, `ksuid`, `xid`, `objectId`, `isbn`, `semVer` | identifiers by shape: `ULID`, `Cuid2`, `NanoID`, `KSUID`, `XID`, `ObjectID`, `ISBN`, `SemVer` |
+| `base64`, `base64Url`, `hexadecimal`, `jwt`, `sha256`, `sha512` | encodings and digests; `base64` has the format `byte` and is generated as `z.base64()` |
+| `nonEmptyString`, `emoji` | a string with a visible character; one emoji |
+| `positiveInt`, `nonNegativeInt`, `negativeInt`, `nonPositiveInt`, `safeInt`, `port`, `positiveFloat`, `nonNegativeFloat`, `negativeFloat`, `nonPositiveFloat`, `bigInt`, `long` | the numbers: `int32` bounds, JavaScript's safe integers, TCP ports, floats by sign, and 64-bit (`long`, `format: int64`) or larger (`bigInt`) integers as strings |
+| `date`, `dateTime`, `time`, `localDateTime`, `localTime`, `isoDuration`, `utcOffset`, `timeZone`, `timestamp` | dates, times and durations as RFC 3339 and ISO 8601 write them |
+| `latitude`, `longitude` | decimal degrees, as numbers |
+| `hexColorCode`, `rgb`, `rgba`, `hsl`, `hsla` | CSS colors |
+| `emailAddress`, `hostname`, `httpUrl`, `ipV4`, `ipV6`, `ip`, `cidrV4`, `cidrV6`, `mac`, `phoneNumber` | addresses; `httpUrl` is named so because `url` is TypeSpec's |
+| `countryCode`, `locale`, `currency`, `iban` | ISO and BCP 47 codes, by shape |
 | `Timestamps` | `createdAt`, `updatedAt: utcDateTime`, read-only |
 | `SoftDelete` | `deletedAt: utcDateTime \| null`, read-only |
 | `Versioned` | `version: integer`, read and update |
@@ -600,8 +653,8 @@ envelope and the rate limit's headers.
   `3.1.0/openapi.yaml` and `3.2.0/openapi.yaml`: point the generator's input
   at one of them.
 - **The library's schema names are global.** `BadRequestBody` …
-  `InternalServerErrorBody`, `ValidationIssue`, `ValidationTarget`, `Uuid`,
-  `Email`, and each `<Item>Page` and `<Item>CursorPage` are emitted under
+  `InternalServerErrorBody`, `ValidationIssue`, `ValidationTarget`, the scalars' components
+  (`UUID`, `EmailAddress`, `Latitude`, …), and each `<Item>Page` and `<Item>CursorPage` are emitted under
   those names, without a namespace, once the spec uses them. A model of the
   same name in your spec then fails with `duplicate-type-name`
   ([troubleshooting](docs/troubleshooting.md)).
@@ -616,12 +669,16 @@ envelope and the rate limit's headers.
   what a handler answers;
 - [Authentication](docs/guide/auth.md): `JanusAuth`, and the guards'
   replies without a body;
+- [Scalars](docs/guide/scalars.md): every scalar of `@nxgt/graphql-scalars`
+  by category, with what each takes and what its pattern leaves out;
 - [Scalars and columns](docs/guide/columns.md): `uuid`, `email`, and the
   columns `@nxgt/drizzle` stamps;
 - [Headers](docs/guide/headers.md): `Idempotency-Key`, the rate limit and
   `Retry-After`;
 - [Sorting](docs/guide/sorting.md): `orderBy` and `direction` beside a
   list's filters, and the `@nxgt/drizzle` call they map to;
+- [Request bodies](docs/guide/requests.md): `CreateRequest`, `UpdateRequest`
+  and `PatchRequest`, and naming your own;
 - [Operation ids](docs/guide/operation-ids.md): `@operationIds`, each
   operation named as written or a verb with its resource, the method each
   verb is sent with, the options, and the ids it refuses;

package/docs/README.md

@@ -5,9 +5,11 @@ The [package README](../README.md) is the short version.
 | Page | Read it when |
 | --- | --- |
 | [Getting started](guide/getting-started.md) | starting a new API project from the `tsp init` template, up to a Hono route |
+| [Request bodies](guide/requests.md) | naming the body of a create, a `PUT` and a `PATCH`: `CreatePostRequest`, `UpdatePostRequest`, `PatchPostRequest` |
 | [Error replies](guide/errors.md) | declaring what an operation answers when it fails |
 | [Pagination](guide/pagination.md) | listing a collection a page at a time |
 | [Authentication](guide/auth.md) | protecting an operation with a `@nxgt/janus` session |
+| [Scalars](guide/scalars.md) | typing a latitude, a currency, an IP address or a port, and knowing what each pattern leaves out |
 | [Scalars and columns](guide/columns.md) | typing ids and addresses, and the columns a row carries |
 | [Headers](guide/headers.md) | making a write idempotent, or declaring a rate limit |
 | [Sorting](guide/sorting.md) | letting a client filter and sort a list |

package/docs/guide/auth.md

@@ -91,7 +91,7 @@ operation can declare the guard's 401 and the handler's 403:
 
 ```tsp
 @useAuth(JanusAuth)
-@post createPost(@body post: Create<Post>): {
+@post createPost(@body post: CreateRequest<Post>): {
   @statusCode _: 201;
   @body post: Post;
 } | BadRequest | AuthenticationRequired | Forbidden;

package/docs/guide/columns.md

@@ -1,8 +1,9 @@
 # Scalars and columns
 
-Two scalars for the strings every API has, and the columns
+Scalars for the ids and addresses every API has, and the columns
 [`@nxgt/drizzle`](https://www.npmjs.com/package/@nxgt/drizzle) stamps a row
-with, as models to spread.
+with, as models to spread. The other scalars, by category, are in
+[Scalars](scalars.md).
 
 ## Scalars
 
@@ -18,7 +19,7 @@ namespace Blog;
 model Author {
   @visibility(Lifecycle.Read) id: uuid;
   email: email;
-  site?: url;
+  site?: httpUrl;
 }
 
 @route("/authors/{authorId}")
@@ -27,12 +28,25 @@ model Author {
 
 | Scalar | Emitted as | Generated | Refused |
 | --- | --- | --- | --- |
-| `uuid` | `$ref` to the schema `Uuid`: `type: string`, `format: uuid` | `type Uuid = string`, `zUuid = z.guid()` | `42`, in a path, a query or a body |
-| `email` | `$ref` to the schema `Email`: `format: email` | `type Email = string`, `zEmail = z.email()` | `not an address` |
-| `url` | TypeSpec's own: `format: uri`, inline | `z.url()` | `not a url` |
-
-`z.guid()` checks the shape of a UUID, as JSON Schema's `uuid` does, not
-the version and variant bits `z.uuid()` also checks.
+| `uuid` | `$ref` to the schema `UUID`: `type: string`, `format: uuid`, a pattern, `x-nxgt-scalar: UUID` | `type UUID = string`, `zUUID = z.guid().regex(…)` | `42`, a UUID with no hyphens or of version 9, in a path, a query or a body |
+| `email` | an alias of `emailAddress`: `$ref` to the schema `EmailAddress`, `format: email`, a pattern, `x-nxgt-scalar: EmailAddress` | `type EmailAddress = string`, `zEmailAddress = z.string().regex(…)` | `not an address`, `ada@localhost` |
+| `httpUrl` | `$ref` to the schema `URL`: `format: uri`, a pattern for `http:` and `https:`, `x-nxgt-scalar: URL` | `type URL = string`, `zURL = z.string().regex(…)` | `not a url`, `javascript:alert(1)` |
+
+TypeSpec's own `url` takes any scheme, inline, as `z.url()`; `httpUrl` is
+the `http:` and `https:` page address. `httpUrl` and `email` are generated as
+`z.string().regex(…)`: the pattern is the rule, as the generator leaves out
+`z.url()`, which trims its input, and `z.email()`, which refuses
+`ada@x.xn--p1ai`, an internationalised top-level domain `email` accepts.
+
+`uuid` takes an RFC 9562 UUID, any version 1 to 8 with the RFC variant, or
+the nil or the max UUID, in any case, as `@nxgt/graphql-scalars`' `UUID`
+does: the pattern adds those checks to the shape `z.guid()` checks. `uuidV4`,
+`uuidV7` and `guid` (any 8-4-4-4-12 hexadecimal) are the narrower and the
+looser ones. `email` is `emailAddress`, under the name it had first.
+
+The schema names changed in 0.10.0: `Uuid` and `Email` became `UUID` and
+`EmailAddress`, and a UUID of no known version is refused. A spec that needs
+the old shape-only id writes `guid`.
 
 ## Columns
 
@@ -66,9 +80,9 @@ model Post {
 | `Versioned` | `version: integer`, at least 0 | read, update | `version()` |
 | `Actors<Id = uuid>` | `createdBy`, `updatedBy`, `deletedBy: Id \| null` | read | `actors()` |
 
-The server sets every read-only column, so `Create<Post>` and
-`MergePatchUpdate<Post>` leave them out, and the generated `CreatePost` and
-`PostMergePatchUpdate` have no `createdAt` a client could send.
+The server sets every read-only column, so `CreateRequest<Post>` and
+`PatchRequest<Post>` leave them out, and the generated `CreatePostRequest` and
+`PatchPostRequest` have no `createdAt` a client could send.
 `Actors<string>` or `Actors<integer>` match `actors('text')` or
 `actors('integer')`.
 
@@ -80,7 +94,7 @@ that version, and throws `OptimisticLockError` otherwise. Declare the
 `Conflict` it becomes:
 
 ```tsp
-@patch updatePost(@path postId: uuid, @body post: MergePatchUpdate<Post>):
+@patch patchPost(@path postId: uuid, @body post: PatchRequest<Post>):
   Post | BadRequest | NotFound | Conflict;
 ```
 
@@ -112,6 +126,6 @@ without it is not checked against the version.
 
 ## Names
 
-`Uuid` and `Email` are schemas of their own, and their names are global: a
-model named `Email` in a spec that also uses `email` collides with it
+`UUID` and `EmailAddress` are schemas of their own, and their names are global: a
+model named `EmailAddress` in a spec that also uses `email` collides with it
 ([troubleshooting](../troubleshooting.md)).

package/docs/guide/errors.md

@@ -143,7 +143,7 @@ A handler may send a 400 of its own, without `issues`. `BadRequestBody`
 describes both, with `issues` optional:
 
 ```tsp
-@patch updatePost(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
+@patch patchPost(@path postId: string, @body post: PatchRequest<Post>): Post | BadRequest;
 ```
 
 The generator declares the validators' 400 itself, as `ValidationErrorBody`,

package/docs/guide/getting-started.md

@@ -99,13 +99,16 @@ interface Users {
   get(@path id: uuid): User | GetErrors;
 
   @post
-  create(@body user: Create<User>): {
+  create(@body user: CreateRequest<User>): {
     @statusCode _: 201;
     @body user: User;
   } | CreateErrors;
 
+  @put
+  update(@path id: uuid, @body user: UpdateRequest<User>): User | UpdateErrors;
+
   @patch
-  update(@path id: uuid, @body user: MergePatchUpdate<User>): User | UpdateErrors;
+  patch(@path id: uuid, @body user: PatchRequest<User>): User | UpdateErrors;
 
   @delete
   delete(@path id: uuid): NoContentResponse | DeleteErrors;
@@ -113,7 +116,10 @@ interface Users {
 ```
 
 `@operationIds` names the operations `listUsers`, `getUser`, `createUser`,
-`updateUser` and `deleteUser` ([Operation ids](operation-ids.md)).
+`updateUser`, `patchUser` and `deleteUser` ([Operation ids](operation-ids.md)).
+`update` replaces the whole user with a `PUT` (`UpdateRequest`), `patch`
+changes some of it with a merge patch (`PatchRequest`); see
+[Request bodies](requests.md).
 
 ```ts
 // openapi-codegen.config.ts
@@ -250,13 +256,16 @@ interface Pets {
   get(@path id: uuid): Pet | GetErrors;
 
   @post
-  create(@body pet: Create<Pet>): {
+  create(@body pet: CreateRequest<Pet>): {
     @statusCode _: 201;
     @body pet: Pet;
   } | CreateErrors;
 
+  @put
+  update(@path id: uuid, @body pet: UpdateRequest<Pet>): Pet | UpdateErrors;
+
   @patch
-  update(@path id: uuid, @body pet: MergePatchUpdate<Pet>): Pet | UpdateErrors;
+  patch(@path id: uuid, @body pet: PatchRequest<Pet>): Pet | UpdateErrors;
 
   @delete
   delete(@path id: uuid): NoContentResponse | DeleteErrors;
@@ -264,8 +273,8 @@ interface Pets {
 ```
 
 The operation names stay; `@operationIds` takes the resource from the
-interface, so the ids become `listPets`, `getPet`, `createPet`, `updatePet`
-and `deletePet`. Run `tsp compile .` and `nxgt-openapi generate` again, and
+interface, so the ids become `listPets`, `getPet`, `createPet`, `updatePet`,
+`patchPet` and `deletePet`. Run `tsp compile .` and `nxgt-openapi generate` again, and
 the generated types, `Pet` and `PetPage`, follow. A name the singular rule
 does not know takes `@operationIds(#{ singular: "…" })` on the interface
 ([Operation ids](operation-ids.md)).

package/docs/guide/headers.md

@@ -19,7 +19,7 @@ namespace Blog;
 
 @route("/posts")
 interface Posts {
-  @post createPost(...IdempotencyKeyHeader, @body post: Create<Post>): {
+  @post createPost(...IdempotencyKeyHeader, @body post: CreateRequest<Post>): {
     @statusCode _: 201;
     ...IdempotentReplayedHeader;
     @body post: Post;
@@ -48,7 +48,7 @@ lock, gets one 409 with the description of the first, and the library warns,
 ## A rate limit
 
 ```tsp
-@post createPost(@body post: Create<Post>): {
+@post createPost(@body post: CreateRequest<Post>): {
   @statusCode _: 201;
   ...RateLimitHeaders;
   @body post: Post;

package/docs/guide/operation-ids.md

@@ -147,7 +147,7 @@ Give the operation its verb's method, or a name that is not a verb, which
 is then its id as written:
 
 ```tsp
-@patch @route("/{id}") update(@path id: uuid, @body user: User): User;  // updateUser
+@put @route("/{id}") update(@path id: uuid, @body user: User): User;    // updateUser
 @post @route("/lookup") lookUpUser(@body id: uuid): User;                // lookUpUser
 ```
 

package/docs/guide/requests.md

@@ -0,0 +1,145 @@
+# Request bodies
+
+`CreateRequest<T>`, `UpdateRequest<T>` and `PatchRequest<T>` are TypeSpec's own
+`Create`, `Update` and `MergePatchUpdate` with a name template, so the body of
+each write is a component with a name you can read: `CreatePostRequest`.
+
+## Why names
+
+TypeSpec's templates name what they emit from the model: `Create<Post>` is
+the component `CreatePost` and `MergePatchUpdate<Post>` is
+`PostMergePatchUpdate`. Two conventions in one spec, and a type in the
+generated client that reads unlike the rest. The aliases give each body the
+name `<Verb><Model>Request`, and `@nxgt/openapi-codegen` generates the types
+and the Zod schemas under it.
+
+## The smallest example
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+model Post {
+  @visibility(Lifecycle.Read) id: uuid;
+  @minLength(1) title: string;
+  body: string;
+  tags?: string[];
+  ...Timestamps;
+  ...Versioned;
+}
+
+@route("/posts")
+interface Posts {
+  @post createPost(@body post: CreateRequest<Post>): {
+    @statusCode _: 201;
+    @body post: Post;
+  } | BadRequest;
+
+  @put updatePost(@path postId: uuid, @body post: UpdateRequest<Post>):
+    Post | BadRequest | NotFound | Conflict;
+
+  @patch patchPost(@path postId: uuid, @body post: PatchRequest<Post>):
+    Post | BadRequest | NotFound | Conflict;
+}
+```
+
+| Alias | Is | Component | Content type | Properties |
+| --- | --- | --- | --- | --- |
+| `CreateRequest<T>` | `Create<T, "Create{name}Request">` | `CreatePostRequest` | `application/json` | those visible on create, as `T` declares them |
+| `UpdateRequest<T>` | `Update<T, "Update{name}Request">` | `UpdatePostRequest` | `application/json` | those visible on update, as `T` declares them |
+| `PatchRequest<T>` | `MergePatchUpdate<T, "Patch{name}Request">` | `PatchPostRequest` | `application/merge-patch+json` | those visible on update, all optional |
+
+```ts
+import type {
+	CreatePostRequest,
+	PatchPostRequest,
+	UpdatePostRequest,
+} from './generated/types';
+```
+
+```tsp
+alias CreateRequest<T extends Reflection.Model> = Create<T, "Create{name}Request">;
+alias UpdateRequest<T extends Reflection.Model> = Update<T, "Update{name}Request">;
+alias PatchRequest<T extends Reflection.Model> = MergePatchUpdate<T, "Patch{name}Request">;
+```
+
+Read-only properties (`id`, `Timestamps`, `Actors`) are in none of the three.
+`version` from `Versioned` is read and update, so it is in
+`UpdatePostRequest` and `PatchPostRequest`, and not in `CreatePostRequest`.
+
+## `PUT` replaces, `PATCH` merges
+
+`UpdateRequest<Post>` is the whole resource: each property is as optional as
+`Post` declares it, so `title` is required and `tags?` is not. Send it with
+`@put`.
+
+`PatchRequest<Post>` is a JSON Merge Patch: every property is optional, and a
+nullable one is sent as `null` to clear it. The body's content type is
+`application/merge-patch+json`, where the others are `application/json`.
+
+```yaml
+# openapi.yaml (excerpt)
+PUT:
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpdatePostRequest'
+PATCH:
+  requestBody:
+    content:
+      application/merge-patch+json:
+        schema:
+          $ref: '#/components/schemas/PatchPostRequest'
+```
+
+A client sending a patch sets the header `Content-Type:
+application/merge-patch+json`. The component `UpdatePostRequest` requires
+`title`; `PatchPostRequest` requires nothing.
+
+## Nested models
+
+A nested model the template filters is named by the same template; one it
+leaves whole keeps its name.
+
+```tsp
+model Address {
+  @visibility(Lifecycle.Read) id: uuid;
+  street: string;
+}
+
+model Author {
+  @visibility(Lifecycle.Read) id: uuid;
+  name: string;
+  address: Address;
+}
+
+@post createAuthor(@body author: CreateRequest<Author>): Author;
+// CreateAuthorRequest.address is CreateAddressRequest, without `id`
+```
+
+A model with no property the filter changes, such as a `Tag` with only
+`name`, is referenced under its own name, `Tag`.
+
+## Your own name template
+
+The aliases fix the convention. Another one is the same template, inline, and
+`Create<T>` and `MergePatchUpdate<T>` stay usable:
+
+```tsp
+@post createPost(@body post: Create<Post, "New{name}">): Post;   // NewPost
+@patch patchPost(@path postId: uuid, @body post: MergePatchUpdate<Post, "{name}Changes">): Post;
+```
+
+`{name}` is the model's name. Without a template, TypeSpec names the
+components `CreatePost` and `PostMergePatchUpdate`.
+
+## Next
+
+The columns a request leaves out are on [Scalars and columns](columns.md); the
+errors a write answers on [Error replies](errors.md).