Area guide · 2 packages · Define a reusable input/output model
Schemas, types and results
Make input, output, serialization and failure behavior explicit across the boundaries your product exposes.
What are you trying to do?
- How do Zod, JSON Schema and GraphQL representations relate?
- Where do standard results and errors live?
- Which types are runtime validation and which are compile-time helpers?
Why start with these packages
Suggested entry point
@lssm-tech/lib.schemaUse schema models and the existing Zod, JSON Schema, GraphQL and entity surfaces.
Suggested entry point
@lssm-tech/lib.contracts-spec-coreUse canonical result and query primitives shared by contracts and adapters.
Suggested entry point
@lssm-tech/lib.utils-typescriptUse existing utility types for compile-time transformations without confusing them with runtime validation.
Practical steps
Step 01
Inspect both directions
Follow one input from its schema to transport parsing, then follow one output back through serialization. Include an absent field, an invalid value and an enum value that needs wire-name conversion in your review of the existing tests.
Step 02
Compare the actual exported leaf
Open the package export map and the selected schema implementation. Check whether the consumer needs the root, entity, or individual projection entry. Use the same canonical model rather than creating parallel definitions for each transport.
Step 03
Exercise a meaningful mismatch
Use the owning project’s schema tests to examine how rejected input becomes a declared result. Add a case only when it resolves a real integration risk, such as a projection collision or an error shape that a client cannot interpret.
Choose a representation intentionally
The schema package provides SchemaModel, field/scalar/enum helpers, entity definitions and explicit projection surfaces for Zod, JSON Schema and GraphQL. Pick the model that the consuming contract already uses, then inspect how its selected transport obtains a wire schema. TypeScript utility types serve a different purpose: they help code describe transformed values at compile time. They do not establish that an incoming request satisfies the same rules. Keep the runtime validation boundary visible in the operation or adapter you are integrating.
Understand projection differences
A schema projection may change the representation while preserving domain meaning. EnumType is a concrete example: domain strings remain unchanged in Zod and JSON Schema, while GraphQL requires valid enum identifiers. The documented projection replaces invalid characters, prefixes unsuitable leading forms and rejects resulting name collisions. Parsing and serialization map the wire name back to the domain value. Review such rules before sharing enums between REST, GraphQL, stored records and UI selections; matching labels alone are insufficient.
Use one result vocabulary
Portable Core exposes results, standard outcomes, normalization and compatibility helpers alongside query envelopes. Read these definitions before wrapping a successful value or error in a new application-specific shape. A field-validation failure, policy denial, unavailable provider and handler failure are different situations for a caller. Preserve their declared meaning through the adapter and the user interface. Keep sensitive implementation details out of a public error while retaining a safe correlation path for diagnostics.
Follow a practical path.
Inspect both directions
Follow one input from its schema to transport parsing, then follow one output back through serialization. Include an absent field, an invalid value and an enum value that needs wire-name conversion in your review of the existing tests.
Compare the actual exported leaf
Open the package export map and the selected schema implementation. Check whether the consumer needs the root, entity, or individual projection entry. Use the same canonical model rather than creating parallel definitions for each transport.
Exercise a meaningful mismatch
Use the owning project’s schema tests to examine how rejected input becomes a declared result. Add a case only when it resolves a real integration risk, such as a projection collision or an error shape that a client cannot interpret.
Packages in this area (2)
2 of 2 shown
- Open manual →
Schema utilities for Zod, JSON Schema, and GraphQL
Use schema models and the existing Zod, JSON Schema, GraphQL and entity surfaces.
- Open manual →
TypeScript utility types and helpers
Use existing utility types for compile-time transformations without confusing them with runtime validation.