id-param

Purpose

Provides Zod schemas for URL path parameter objects carrying resource identifiers. Rather than validating raw strings ad-hoc in every route handler, all Suaveplan endpoints that accept an :id segment share this schema, ensuring consistent error messages, type inference, and zero-duplication across the server plugin layer and generated OpenAPI documents.

Features

IdParam object schema — validates a single {id: string} path parameter (non-empty)
NestedIdParam object schema — validates {parentId, id} pairs for nested resource routes (e.g. /orgs/:orgId/members/:id)
Both schemas enforce non-empty strings, catching blank or missing identifiers before any database query is attempted
Full TypeScript inference via z.infer<> — no manual interface duplication
Zod v4 compatible

Usage: Basic Example

import { IdParam } from "@suaveplan/api-schemas/common";

// Validate route params from an HTTP framework
const params = IdParam.parse({ id: "user_01J8ZGCZ7ECTFAKEUID123456" });
// → { id: "user_01J8ZGCZ7ECTFAKEUID123456" }

Usage: Advanced Example

import { NestedIdParam } from "@suaveplan/api-schemas/common";

// Validate nested resource route params: /orgs/:parentId/members/:id
function getMember(rawParams: unknown) {
  const { parentId, id } = NestedIdParam.parse(rawParams);
  return db.member.findUnique({ where: { id, orgId: parentId } });
}

API Reference

`IdParam`

Zod object schema for single-resource routes.

Field	Type	Description
`id`	`string` (min 1)	Non-empty resource identifier from URL segment

Type export: type IdParam = z.infer<typeof IdParam>

`NestedIdParam`

Zod object schema for nested-resource routes.

Field	Type	Description
`parentId`	`string` (min 1)	Parent resource identifier
`id`	`string` (min 1)	Child resource identifier

Type export: type NestedIdParam = z.infer<typeof NestedIdParam>

Implementation Notes

Both schemas use z.string().min(1) rather than additional format constraints (UUID, ULID, etc.) to keep them format-agnostic. Suaveplan uses multiple ID formats depending on the domain (ULIDs for user-facing resources, SHA hashes for content-addressable objects, numeric sequences for legacy integrations). Services that require a specific format should compose these schemas with .refine() or .regex() at the route layer rather than tightening the shared base schema.

2.7 KiB Raw Blame History