Askr
Server & APIs

Schemas

Use schemas with the current published Askr packages.

  • @askrjs/schema0.0.2

How to use schemas

Start with this complete schemas shape, then replace the example data and application service with your own.

  1. Import the published @askrjs/schema entrypoint.
  2. Keep schemas configuration next to the component, route, or server composition root that owns it.
  3. Handle pending, unavailable, cancellation, and failure states, then verify the production path.
const project = schema.object({
  id: schema.string(),
  name: schema.string(),
});

project.jsonSchema;

Schema construction

schema.object({...}), schema.string(), schema.number(), schema.integer(), schema.boolean(), schema.array(items), schema.enum([...]), schema.literal(value), schema.optional(s), schema.nullable(s), and schema.oneOf/anyOf/allOf(...) compose into a Schema<T> whose runtime type is recovered with InferSchema<typeof s>. schema.object() and schema.record() specifically return an ObjectSchema, the subtype required wherever a schema needs to describe a whole request object — route params, query, and operation inputs in @askrjs/server.

Safe parsing

Every Schema exposes safeParse(value), returning { success: true, data } on success or { success: false, issues } on failure — never a thrown exception. Objects built with schema.object() reject any key you didn't declare unless you pass additionalProperties: true or cover the extra keys with schema.record().

jsonSchema

Each schema carries a readonly jsonSchema property alongside its safeParse() parser, so the exact declaration that validates a value at runtime is also what gets projected into OpenAPI documentation — there's no separate hand-written schema to keep in sync. schema.raw(jsonSchema, safeParse) exists for the rare case where an integration needs to own a custom format outside the built-in vocabulary, and it still requires a real parser rather than accepting a documentation-only stub.

Error reporting

A failed safeParse() returns an issues array of { path, message, code } objects, where path is a stable array of string or number segments pointing at the offending key or array index. That's precise enough to drive a field-level form error, or to log a structured line, without parsing a message string to figure out what actually broke.