# Schema Update > Use when updating the SDK GraphQL schema from a local or staging API server - Skill: `tomevault-io/schema-update` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/schema-update` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/schema-update/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/schema-update --- # Update GraphQL Schema Updates the SDK's GraphQL schema and related types from an API server instance. ## Usage ``` /schema-update local # Download from local server /schema-update staging # Download from staging server /schema-update # Will prompt for server choice ``` ## Checklist **You MUST use TodoWrite to create a todo for EACH step below. Mark each complete only after verification.** ### Download Schema - [ ] Determine server source (from argument or ask user): `local` or `staging` - [ ] Run schema download from `packages/graphql`: - Local: `pnpm gql:download:local` - Staging: `pnpm gql:download:staging` - [ ] Run `pnpm gql:generate:introspection` to generate GraphQL documents ### Update Documents - [ ] Cross-reference `packages/graphql/schema.graphql` with existing GQL documents - [ ] Add missing fields to existing fragments - [ ] Introduce new fragments if necessary - [ ] If new queries or mutations exist in schema, ask user if they should be added ### Check for New Enums - [ ] Search for new `enum` definitions in `packages/graphql/schema.graphql` - [ ] For each new enum: - Add enum definition to `packages/graphql/src/enums.ts` with JSDoc comments - Import the enum type in `packages/graphql/src/graphql.ts` - Add scalar binding in `graphql` config (alphabetically ordered) - [ ] Note: Do NOT create separate type exports for enums - the enum definition serves as both value and type ### Export Input Types - [ ] Check for new input types in schema - [ ] Common types (used across multiple queries): export from `packages/graphql/src/inputs.ts` - [ ] Query-specific types: colocate with corresponding query files (permits.ts, transactions.ts, swaps.ts, user.ts, reserve.ts, hub.ts, misc.ts) - [ ] Use pattern: `export type InputName = ReturnType>;` - [ ] Exclude fork-related input types unless explicitly needed - [ ] Ensure scalar bindings exist in `graphql.ts` for all input types ### Update URQL Cache Configuration Update `packages/client/src/cache.ts` to handle new/removed types: #### Keys Section - [ ] **Add new types with `id` field**: Type the `data` parameter with the fragment type from `@aave/graphql` and return `data.id`. ```typescript NewTypeName: (data: NewTypeName) => data.id, ``` - [ ] **Add ephemeral types** (value objects without stable identity): Return `null` to disable normalization ```typescript NewValueObject: () => null, ``` - [ ] **Remove deleted types**: Remove any types that no longer exist in the schema - [ ] **When unsure**: If you're uncertain whether it needs normalization, ask the user #### Resolvers Section Add field transformers for enhanced client-side types: - [ ] **DateTime fields**: Transform to JavaScript `Date` objects ```typescript TypeName: { dateField: transformToDate, // for non-nullable DateTime nullableDateField: transformToNullableDate, // for nullable DateTime }, ``` - [ ] **BigDecimal fields**: Transform to `BigDecimal` class instances ```typescript TypeName: { decimalField: transformToBigDecimal, // for non-nullable BigDecimal nullableDecimalField: transformToNullableBigDecimal, // for nullable BigDecimal }, ``` - [ ] **BigInt fields**: Transform to native BigInt ```typescript TypeName: { bigIntField: transformToBigInt, }, ``` #### Common Patterns - Activity types (`*Activity`) typically have `timestamp: DateTime!` → use `transformToDate` - Types with `createdAt: DateTime` (nullable) → use `transformToNullableDate` - Types with `createdAt: DateTime!` (non-nullable) → use `transformToDate` - Health factor types have nullable `BigDecimal` fields → use `transformToNullableBigDecimal` ### Validate **IMPORTANT: Do not mark the schema update complete until build and all tests pass.** - [ ] Run `pnpm check` from `packages/graphql` to verify document integrity - [ ] Run `pnpm build` to ensure TypeScript compilation succeeds - If build fails, fix the errors and re-run `pnpm build` - Repeat until build succeeds with zero errors - [ ] Run `pnpm test --run` to verify tests pass - If tests fail, analyze failures, fix the code, and re-run tests - If the fix was in a sub-package compared to where the tests failed, re-run `pnpm build` first - Repeat until all tests pass - [ ] Run `pnpm lint:fix` to format code - [ ] Confirm both build and tests pass before marking complete ## Code Patterns ### Enum Definition (enums.ts) ```typescript /** * Description of what this enum represents. */ export enum EnumName { /** * Description of this value */ VALUE_ONE = 'VALUE_ONE', /** * Description of this value */ VALUE_TWO = 'VALUE_TWO', } ``` ### Scalar Binding (graphql.ts) ```typescript // Add to imports import type { ..., EnumName } from './enums'; // Add to scalars config (alphabetically) scalars: { ... EnumName: EnumName, ... } ``` ### Input Type Export ```typescript export type InputName = ReturnType>; ``` ## Stop Conditions | Condition | Action | |-----------|--------| | Schema download fails | Check if server is running, verify URL | | `pnpm check` fails | Fix document errors before proceeding | | Build fails | Fix TypeScript errors, re-run build until it passes | | Tests fail | Investigate and fix failing tests, re-run until all pass | **Never mark the schema update as complete while build errors or test failures exist.** The iterative fix-and-verify loop is mandatory. ## Common Mistakes 1. **Creating type exports for enums** - Enums are both values and types; don't use `ReturnType>` 2. **Adding new queries/mutations without being asked** - Only update existing documents unless explicitly requested 3. **Forgetting scalar bindings** - Every input type needs a corresponding entry in `graphql.ts` 4. **Non-alphabetical ordering** - Scalar bindings should be alphabetically ordered 5. **Missing JSDoc comments** - All enums should have documentation 6. **Forgetting cache.ts updates** - New types need keys configuration; types with DateTime/BigDecimal/BigInt need resolvers 7. **Wrong nullable transformer** - Use `transformToNullableDate`/`transformToNullableBigDecimal` for nullable fields, non-nullable variants for required fields 8. **Missing type imports in cache.ts** - Add imports for any new types used in the keys section 9. **Marking complete with failing build/tests** - Always run `pnpm build` and `pnpm test --run` and fix all errors before marking complete --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/aave) — claim your Tome and manage your conversions.