Skip to content
ContractSpec
Start here

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.schema

Use schema models and the existing Zod, JSON Schema, GraphQL and entity surfaces.

Read package manual →

Suggested entry point

@lssm-tech/lib.contracts-spec-core

Use canonical result and query primitives shared by contracts and adapters.

Read package manual →

Suggested entry point

@lssm-tech/lib.utils-typescript

Use existing utility types for compile-time transformations without confusing them with runtime validation.

Read package manual →

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

  • lib.schemaSuggested entry pointfoundationnode

    Schema utilities for Zod, JSON Schema, and GraphQL

    Use schema models and the existing Zod, JSON Schema, GraphQL and entity surfaces.

    Open manual →
  • lib.utils-typescriptSuggested entry pointfoundationnode

    TypeScript utility types and helpers

    Use existing utility types for compile-time transformations without confusing them with runtime validation.

    Open manual →