GraphQL
A read/write GraphQL endpoint compiled from the same schema.json.
The GraphQL adapter compiles the same objects/<name>/schema.json into a GraphQL schema and mounts
a /graphql endpoint — a third protocol alongside REST and MCP, sharing one data model and one
security layer. It is opt-in (disabled unless declared).
// weavekit.config.ts
import type { EngineConfig } from '@weave-kit/engine';
export default {
adapters: { graphql: { enabled: true, prefix: '/graphql' } }, // prefix defaults to /graphql
} satisfies EngineConfig;Authentication is the same Bearer API key as REST/MCP; a missing/invalid key is a plain 401.
Authorization is not re-implemented: every field resolves through the RBAC-decorated data-access
layer, so row scope (own/department), field exclusion and write auditing behave exactly as they do
over REST/MCP.
The schema
For an object leads the compiler emits:
type Leads { weave_id: ID!, title: String, status: LeadStatus, owner: Users, lines: [OrderLines!]!, tags: [Tags!]! }
type LeadsPage { rows: [Leads!]!, total: Int! }
type Query {
leads(filter: JSON, sort: [SortInput!], limit: Int, offset: Int): LeadsPage!
leads_by_id(id: ID!): Leads
}
type Mutation {
createLeads(data: LeadsCreateInput!): Leads!
updateLeads(id: ID!, changes: LeadsUpdateInput!): Leads!
deleteLeads(id: ID!): Boolean!
transitionLeads(id: ID!, action: String!, payload: JSON): Leads! # only when the object has a workflow
}idis the record'sweave_id(itsrecord_key), not the raw primary key — read it from a result (weave_id) and pass it back.filteris the free-form JSON filter (exact values, operator objects, top-level$or) — the same contract as REST/MCP.sortis a[SortInput!]({ field, dir: asc|desc }).- Relations are nested: a
relation/user/departmentfield resolves to the target object (or its raw id when the target isn't a modeled object),details/multiRelationto[Target!]!. Nested reads are batched per request, so a list of N records with a relation is one query per layer. create/updateinput types expose only writable, non-excluded fields; the primary key is immutable on update. Writes go through the same data-access path, so RBAC denials surface asrbac.denied.create|update|deleteand every write is audited.
Errors use the GraphQL-over-HTTP shape: HTTP 200 with { errors: [{ message, extensions: { code } }] }
(code is the engine's stable error code). Authentication failures stay 401.
Hardening
adapters: {
graphql: {
enabled: true,
security: {
maxDepth: 10, // default 10
maxComplexity: 5000, // optional
maxAliases: 50, // optional
introspection: false, // default true
allowList: { enabled: true, file: 'graphql-allowlist.json' }, // default off
},
rateLimit: { windowMs: 60_000, max: 600 }, // per Bearer key
},
},- depth / complexity / alias limits are enforced before execution; a rejected query returns
graphql.depthExceeded/graphql.complexityExceeded/graphql.aliasExceeded. introspection: falserejects__schema/__type.- Allow list (
allowList.file, Git-versioned): only operations whose hash is listed run; others returngraphql.allowList.denied. The hash isoperationHash(document)(sha256 of the printed document). Keep the file in your repository so the approved surface is reviewable.
Export the SDL
weave graphql:schema --out schema.graphql # or omit --out to print to stdoutThe export is offline (no database) — useful for client codegen or review.
Related
- Schema guide — the single source of truth
- RBAC — the row- and field-level rules GraphQL reuses
- CLI reference —
weave graphql:schema - Public API —
buildGraphQLSchema,registerGraphQL