doc: formatting IDs

docs/modeling/model.md

@@ -144,6 +144,8 @@ model User {
 }
 ```
 
+### Default values
+
 A default value can be specified for a field with the `@default` attribute. The value can be a literal, an enum value, or a supported function call, including:
 
 - `now()`: returns the current timestamp
@@ -162,6 +164,15 @@ model User {
 }
 ```
 
+Functions that generate `String` ids (`cuid()`, `uuid()`, `ulid()`, `nanoid()`) takes an optional `format` argument to allow passing in a pattern that controls the output format. `%s` in the pattern will be replaced by the generated id. For example:
+
+```zmodel
+model User {
+    // generate a UUID v4 with "user_" prefix
+    id String @id @default(uuid(4, "user_%s"))
+}
+```
+
 ## Native type mapping
 
 Besides giving a field a type, you can also specify the native database type to use with the `@db.` series of attributes.

docs/orm/formatting-ids.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 13
+description: Formatting IDs in ZModel
+---
+
+import ZenStackVsPrisma from '../_components/ZenStackVsPrisma';
+
+# Formatting IDs
+
+<ZenStackVsPrisma>
+ID formatting is a ZModel feature and doesn't exist in Prisma.
+</ZenStackVsPrisma>
+
+Prefixing and suffixing model IDs is becoming more common in database design, usually by including the model name in the generated ID. This aids debugging and troubleshooting because developers can easily spot when an ID of one model has been passed to a service expecting an ID of another model.
+
+ZenStack supports this pattern via a new `format` parameter added to every ID function. Simply pass a format string to the function, and it will replace the `%s` sequence with the generated ID.
+
+:::info
+* Not all ID functions have the same signature. See [the function reference](../reference/zmodel/function#predefined-functions) for more details.
+* It is considered an error if the format string does not contain `%s`
+:::
+
+```zmodel title='/schema.zmodel'
+model User {
+    id String @id @default(uuid(7, 'user_%s'))
+    ...
+}
+```
+
+In the future, this pattern may be implemented via the `@default` attribute directly, which would allow IDs to be generated via complex expressions rather than string formatting.

docs/reference/zmodel/function.md

@@ -89,35 +89,54 @@ Functions related to input validation are documented in a [separate page](./inpu
 ### uuid()
 
 ```zmodel
-function uuid(): String {}
+function uuid(version: Int?, format: String?): String {}
 ```
 
 Generates a globally unique identifier based on the UUID spec.
 
+*Parameters:*
+
+- `version` (optional): The UUID version to generate. Supported values are `4` (default) and `7`.
+- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.
+
 ### cuid()
 
 ```zmodel
-function cuid(version: Int?): String {}
+function cuid(version: Int?, format: String?): String {}
 ```
 
-Generates a unique identifier based on the [CUID](https://github.com/ericelliott/cuid) spec. Pass `2` as an argument to use [cuid2](https://github.com/paralleldrive/cuid2).
+Generates a unique identifier based on the [CUID](https://github.com/ericelliott/cuid) spec.
+
+*Parameters:*
+
+- `version` (optional): The CUID version to generate. Supported values are `1` (default) and `2`.
+- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.
 
 ### nanoid()
 
 ```zmodel
-function nanoid(length: Int?): String {}
+function nanoid(length: Int?, format: String?): String {}
 ```
 
 Generates an identifier based on the [nanoid](https://github.com/ai/nanoid) spec.
 
+*Parameters:*
+
+- `length` (optional): The length of the generated id.
+- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.
+
 ### ulid()
 
 ```zmodel
-function ulid(): String {}
+function ulid(format: String?): String {}
 ```
 
 Generates a unique identifier based on the [ULID](https://github.com/ulid/spec) spec.
 
+*Parameters:*
+
+- `format` (optional): A pattern to control the output format. `%s` in the pattern will be replaced by the generated id. Use escaped `\\%s` to have a literal `%s` in the output.
+
 ### now()
 
 ```zmodel