# Schemas, types and results

Make input, output, serialization and failure behavior explicit across the boundaries your product exposes.

Source snapshot: bcc79fcc27c4d801c2119bef81ddcce7b4e86498

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

Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/schema/README.md
Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/contracts-spec/README.md

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

Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/schema/README.md
Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/contracts-spec/README.md

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

Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/schema/README.md
Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/contracts-spec/README.md

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

Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/schema/README.md
Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/contracts-spec/README.md

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

Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/schema/README.md
Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/contracts-spec/README.md

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

Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/schema/README.md
Source: https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/foundation/contracts-spec/README.md

## Packages

- [@lssm-tech/lib.schema](https://lssm.co/docs/packages/lib.schema/): Schema utilities for Zod, JSON Schema, and GraphQL
- [@lssm-tech/lib.utils-typescript](https://lssm.co/docs/packages/lib.utils-typescript/): TypeScript utility types and helpers