Keep the User graph honest.

Validation works on the graph we already know.

Use the same example from the Items page: Alex Morgan is a User, Acme Systems is a Company, Alex has many Addresses, and a Team membership carries a role. Validation does not decide your business rules; it verifies the structural contracts that let those relationships travel safely through the system.

1. Validate identity and location.

Fjell distinguishes a primary key from a composite key. That distinction makes the User graph explicit in code.

import { validatePK, validateKeys } from "@fjell/validation";

// Alex is a primary User Item.
validatePK(alex, "user");

// Alex's home Address is contained by a User.
validateKeys(homeAddress, ["address", "user"]);

If an Address arrives with the wrong key type or the wrong parent location, validation fails before the operation continues. This is where a PItem-to-many-CItem relationship gets a structural guardrail.

2. Validate the Item payload.

Keys tell Fjell where an Item lives. Your application still owns the domain properties. Validate those properties at the boundary before creating or updating an Item.

type UserInput = {
  firstName: string;
  lastName: string;
  birthDate?: string;
  companyId: string;
};

const input: UserInput = request.body;

if (!input.firstName.trim() || !input.lastName.trim()) {
  throw new Error("User must have a first and last name");
}

// The validated payload can now reach User operations.

For an Address, the equivalent boundary might require street, city, and postalCode. For a Team membership, it might restrict role to manager or member. The package supplies Item/key validation; application validators express domain policy.

3. Validate queries before they travel.

Queries are also part of the contract. A request for Alex's active team memberships should be an object with the expected shape—not an array, string, or accidental null.

import { validateQuery, validateOperationParams } from "@fjell/validation";

validateQuery(
  { filter: { role: "manager" }, limit: 20 },
  "team-memberships"
);

validateOperationParams(
  { userId: "u-42", teamId: "team-9" },
  "team-memberships"
);

Bad shapes fail early, with operation-specific errors, instead of becoming confusing storage or router failures.

Where validation sits in the journey.

Validation is an early foundation layer. After it passes, core and lib can apply Item operations, adapters can persist them, and routers can expose the graph over HTTP.