Ariadne: Schema-First GraphQL

This page assumes ariadne and uvicorn are already installed — covered in Getting started with Python GraphQL. Every example below assumes the following imports are in scope:

Where a code-first library like Strawberry derives its schema from Python types, Ariadne starts from the opposite direction: the schema is hand-written GraphQL SDL, typically kept in one or more .graphql files and loaded at startup with load_schema_from_path:

load_schema_from_path accepts either a single file or a directory, concatenating every .graphql file it finds — a common way to split a large schema into one file per type while still loading it as a single SDL document. Because the SDL is the source of truth, nothing about the resolver code below can silently redefine a field’s name or type; a resolver bound to a field that does not exist in the SDL raises at schema-build time instead of drifting unnoticed. The SDL syntax itself, and the Query/Mutation/Subscription root type convention, are language-agnostic and covered in depth in Schema \& type system; this page only covers Ariadne’s own way of loading and binding it.

Ariadne binds a Python function to an SDL field by decorating it with @<binder>.field("fieldName"), where the binder is one instance per SDL type — QueryType() for Query, MutationType() for Mutation, a plain ObjectType("TypeName") for any other object type, and SubscriptionType() for Subscription:

Every resolver receives the same two leading positional arguments the specification’s execution model passes to any field resolver — the parent value (_ when it is unused, as on the Query/Mutation roots) and a GraphQLResolveInfo object — followed by the field’s GraphQL arguments as keyword-shaped positional names matching the SDL. Execution \& resolvers covers this parent-value/arguments/context/info resolver signature language-agnostically; Ariadne’s binders are simply a registry that associates a Python callable with one (Type, field) pair in the SDL, rather than a mechanism that changes the signature itself. A field with no explicit binding falls back to Ariadne’s default resolver, which reads a same-named dictionary key or object attribute off the parent value — adequate for a field like Book.title above, whose value already lives under that name on whatever the parent resolver returned.

make_executable_schema takes the parsed SDL and every binder object, attaches each binder’s resolver functions to the matching SDL fields, and returns a graphql-core GraphQLSchema ready to execute — the same kind of schema object that a code-first library such as Strawberry also ultimately builds and hands to the executor:

Binders are passed positionally and in any order; make_executable_schema inspects each one’s bound type name rather than relying on argument position to know which SDL type it applies to. snake_case_fallback_resolvers, included above, is covered in its own section below — it is a bindable that changes the default resolver Ariadne falls back to when no explicit @binder.field(…​) binding exists for a field, rather than a type binder itself.

ariadne.asgi.GraphQL wraps an executable schema as a complete ASGI application, handling the POST /graphql query/mutation endpoint and, by default, a GET request serving an in-browser GraphQL IDE:

Because GraphQL is a plain ASGI application rather than a FastAPI APIRouter, it is mounted with FastAPI’s (or Starlette’s) generic app.mount(path, asgi_app) rather than include_router — the same mounting mechanism works identically under a bare Starlette application with no FastAPI involved at all. This is the structural difference from strawberry.fastapi.GraphQLRouter, covered in FastAPI \& Strawberry: Strawberry’s router integrates with FastAPI’s own dependency-injection and routing layer, while Ariadne’s ASGI app is transport-framework-agnostic by design and exposes its own hooks (context_value, covered next) instead. See Ariadne — FastAPI integration for the full mounting reference, including serving Ariadne behind a plain Starlette route instead of FastAPI.

Every resolver’s GraphQLResolveInfo.context is populated from the context_value argument to GraphQL(…​), which can be a plain dictionary, a callable returning one, or an async callable — evaluated once per request, before execution begins, mirroring the same request-scoped-context role that context_getter plays for Strawberry’s router:

A resolver then reads info.context["db_session"] or info.context["current_user"] exactly as it would read any other dictionary. Because context_value is an ordinary callable rather than a dependency-injection graph, threading in FastAPI’s own Depends(…​)-based dependencies takes an explicit call inside the callable (as get_db_session() and authenticate(request) do above) rather than FastAPI resolving them automatically — the trade-off for Ariadne’s ASGI app working the same way regardless of which framework mounts it.

A GraphQL scalar declared in the SDL (built-in or custom) needs Python-side serialization and parsing logic attached before it can round-trip real values; ScalarType binds @<scalar>.serializer (Python value to wire value) and @<scalar>.value_parser (wire value to Python value) functions to a scalar name, the same way QueryType/ObjectType bind resolvers to fields:

The bound datetime_scalar is passed to make_executable_schema alongside the other binders, exactly like query/mutation/author_type above. Custom scalars themselves — what belongs in one, and their relationship to the built-in Int/Float/String/Boolean/ID scalars — are covered language-agnostically in Schema \& type system; this section only covers Ariadne’s serializer/value_parser binding mechanism on top of that model.

A field typed as a GraphQL union or interface returns one of several possible concrete object types at runtime, so the executor needs a way to ask, for a given resolved value, which SDL type it actually is — Ariadne answers that with a @<union_or_interface>.type_resolver function registered on a UnionType or InterfaceType binder:

The function returns the name of the concrete SDL type as a string, which the executor uses to select which fields are valid to resolve against the returned value — the same runtime type-discrimination role that a __resolveType function plays in the reference JavaScript implementation and that Interfaces, unions \& inputs describes independently of any particular server library. search_result_type and node_type are passed to make_executable_schema alongside the object-type and root-type binders shown earlier.

SubscriptionType mirrors QueryType/MutationType except each bound field needs two functions: a @subscription.source(…​)-decorated async generator that yields the raw events to push, and the usual @subscription.field(…​) resolver that shapes each yielded event into the field’s return type:

Splitting the event source from the per-event resolver lets the same shaping/formatting logic used by a Query/Mutation field also apply to a subscription’s pushed values, rather than duplicating that logic inside the generator itself. Subscriptions covers the operation type and its WebSocket transport language-agnostically; Ariadne serves subscriptions over WebSocket through the same ariadne.asgi.GraphQL application shown earlier, with no separate app to mount.

GraphQL field names conventionally use camelCase (publishedYear in the SDL above), while idiomatic Python dictionaries and objects conventionally use snake_case (published_year); binding every such field by hand with @query.field(…​) would be needless boilerplate for fields that need no logic beyond that name translation. Passing the snake_case_fallback_resolvers bindable to make_executable_schema, as shown earlier, changes Ariadne’s default fallback resolver (used whenever no explicit binding exists for a field) to look up the snake_case version of a camelCase field name automatically:

This affects only fields with no explicit resolver bound to them — Author.books above still runs the resolve_author_books function shown earlier untouched, since an explicit binding always takes precedence over any fallback.

snake_case_fallback_resolvers is deprecated in current Ariadne releases in favor of passing convert_names_case=True directly to make_executable_schema — the bindable is kept as the explicit, opt-in form and still works, but new schemas should prefer the convert_names_case keyword argument instead:

By default, an unhandled exception raised inside a resolver is caught by graphql-core’s executor and reported in the response’s `errors array as a generic message, with the original exception details available only when the GraphQL app is constructed with debug=True — appropriate for local development, not for a production deployment that should not leak internals to clients:

An error_formatter callable, passed to GraphQL(…​), is given each GraphQLError and the app’s debug flag and returns the dictionary that lands in the response’s errors array — the place to map an application-level exception onto a stable extensions.code, the same convention Response \& error handling documents independently of Ariadne. Raising a GraphQLError directly from a resolver (rather than letting an arbitrary exception surface) is the more common way to attach extensions to a specific field failure without a global formatter at all.

Ariadne’s schema-first workflow is a deliberate trade-off against a code-first library like Strawberry, not a strictly inferior alternative:

Conversely, a greenfield API owned end to end by one Python team, where keeping resolvers and schema mechanically in sync matters more than an SDL file being independently reviewable, is the case FastAPI \& Strawberry's code-first style fits better, as Getting started with Python GraphQL discusses when introducing both libraries side by side.

This page covered enough of Ariadne’s binding workflow to run a schema-first GraphQL server end to end; three related pages go deeper on adjacent concerns: