DEV Community: D Ivanitsky

json_shield: Engineering an AI-Ready Dart Package

D Ivanitsky — Thu, 16 Jul 2026 08:37:03 +0000

Code generation has shifted. The majority of code calling a new pub.dev package is no longer typed by a human reading the documentation; it is generated by LLMs (Copilot, Cursor, Claude) operating within an IDE. If an AI assistant hallucinates your API, the human developer will blame your package and remove it.

Building a package in 2026 requires engineering for two distinct consumers: the compiler and the LLM context window.

This post details the architecture of making json_shield AI-ready. It deconstructs the four artifacts that reach a consumer's AI, the one artifact that steers a contributor's agent, and the deterministic rules for writing them.

The LLM Consumer Architecture

When a developer prompts an assistant to "use json_shield to parse this response", the LLM does not browse the repository. It relies on Retrieval-Augmented Generation (RAG) and its pre-trained weights. Because the package is new, pre-trained weights are zero.

You control exactly four artifacts that the IDE's RAG pipeline will index and inject into the prompt context.

1. The README: Density over Marketing

A README is no longer a sales pitch; it is the primary context injection for an LLM.
LLMs prioritize code blocks and structural formatting over prose.

The Rule: Optimize for token density.

Remove adjectives: "Fast", "easy", and "lightweight" consume tokens without providing structural constraints.
Provide exact input/output pairs: An LLM infers the API contract from examples faster than from text descriptions.
Declare negative constraints explicitly: State what the package cannot do. LLMs hallucinate features when boundaries are undefined. json_shield's README explicitly states: "No HTTP, no retries, no code generation." This prevents the model from attempting to chain guard.decode into a Dio interceptor pipeline that doesn't exist.

2. The `example/` Directory: The Integration Vector

The IDE's language server indexes the example/ folder. When an AI agent searches the local workspace for usage patterns, this folder is the highest-weight reference.

The Rule: The example must be a self-contained, compilable representation of the exact production use case.
Do not write synthetic Foo/Bar examples. json_shield provides a full mock HTTP response, a standard quicktype generated model, and the exact try/catch block for aggregate error reporting. The AI copies the structural logic from here, not the README.

3. Doc Comments (`///`): Inline RAG Injection

When a user hovers over a method or an AI agent requests definitions, the Dart analyzer extracts the /// comments.

The Rule: Doc comments must dictate the contract and the failure mode.
A comment like /// Decodes the JSON is zero-value data. The LLM needs to know the type constraints and exceptions.

/// Decodes a single object from a JSON map.
/// Throws [DecodeException] if the [data] shape mismatches the expected input 
/// before [factory] is invoked.
/// Set [guard.verbose = true] to print payloads to the console.

This forces the AI to wrap the call in a try/catch specifically targeting DecodeException, preventing generic catch (e) block generation.

4. `pubspec.yaml` Description: The Search Heuristic

The 255-character description is the primary string indexed by pub.dev's search and external web scrapers.
Do not use it for branding. Use it as an array of technical keywords.
json_shield description: "A zero-dependency structural guard for fromJson factories. Turns anonymous map casting crashes into actionable, typed error reports with stack traces."

The Contributor's Agent

When another developer forks your repository to add a feature, they will likely use an agentic IDE (like Cursor) to write the PR. Left unconstrained, the agent will introduce external dependencies or break your architectural rules because doing so is statistically common in its training data.

The `rules.md` / `.cursorrules` Artifact

You must provide a machine-readable directive file in the root directory. This acts as a system prompt override for any agent modifying the codebase.

For json_shield, the constraints defined in Part 1 are codified as hard rules:

# Architecture Constraints
- Zero dependencies. Do not add packages to pubspec.yaml.
- Pure Dart. Do not use flutter or dart:ui imports.
- No code generation.
- All modifications must preserve the exact argument order in public APIs: (factory, json).

When an agent is prompted to "add an HTTP client to fetch the schema," this file forces it to reject the prompt, citing the zero-dependency architecture.

Conclusion

API design is no longer just about human ergonomics; it is about machine predictability. A package that is easy for an LLM to parse, index, and generate accurate code for will achieve adoption. A package that relies on human intuition to fill the gaps in its documentation will fail at the generation step. Define the rules, strip the context overhead, and write machine-readable context.

json_shield: Turning Anonymous fromJson Crashes Into Actionable Reports

D Ivanitsky — Tue, 14 Jul 2026 11:47:44 +0000

I'm Dmytro Ivanitsky, a senior developer shipping Flutter since its alpha days. Across 15+ production projects — from eSIM apps to retail payment flows — one specific crash kept billing me hours. I finally packaged the structural fix into json_shield. This post covers its core design decisions; the next one in the series covers making it AI-ready for the assistants that increasingly write the code calling it.

The pain

Every Flutter developer knows this crash report line:

type 'List<dynamic>' is not a subtype of type 'Map<String, dynamic>'

And knows what it doesn't say: which of your 30 endpoints broke, what the backend actually sent, or whether it's one corrupt row or the whole schema. Release stack traces are obfuscated; async gaps shred the logical chain. You end up reproducing production traffic locally to learn that the backend wrapped a plain array into a pagination envelope on Tuesday.

The root cause is structural: fromJson factories (quicktype, json_serializable, hand-written — all of them) are chains of as casts. They're supposed to be brittle; that's the contract check. What's missing is attribution when they fail.

What the same break looks like guarded

The backend renames zip to zipCode three levels deep, inside order.customer.address. Unguarded, that's a bare type 'Null' is not a subtype of type 'String' from somewhere. Guarded:

final order = guard.decode(Order.fromJson, response.data,
    context: 'orders_byId_get');

DecodeException: [orders_byId_get] expected Order, got _Map<String, dynamic>. 
cause: type 'Null' is not a subtype of type 'String'

rawData: {
  "id": "ord_12345",
  "customer": {
    "name": "John Doe",
    "address": {
      "city": "New York",
      "zipCode": "10001"
    }
  }
}

causeTrace:
#0      new Address.fromJson (package:app/models/address.dart:24:36)
#1      new Customer.fromJson (package:app/models/customer.dart:18:24)
#2      new Order.fromJson (package:app/models/order.dart:12:22)
#3      guard.decode (package:json_shield/json_shield.dart:85:14)

One report line answers the triage questions in order: which endpoint (orders_byId_get), which contract (Order on a body that is a map — so the shape is fine, a field inside broke), what kind of break (a String field came back Null). The preserved causeTrace points at the exact line inside Address.fromJson — the nested model three levels down — and in a debug run with guard.verbose = true the exception carries the raw payload — and the failure line above lands in the console by itself, without a breakpoint — the renamed key visible on sight. Ticket to the backend team written in one glance, no local reproduction of production traffic.

Design constraints

The package is engineered specifically for rapid development. To guarantee high iteration velocity and zero integration friction, these four requirements were fixed before any code was written:

Generated models stay untouched. Rapid development means schemas change often. While tools like quicktype.io are highly prevalent in these workflows, the package supports any serializer exposing a fromJson method. Because generated output is overwritten constantly, any manual additions die on the next run: no annotations, no base classes, no secondary code generation.
One operator at the call site. Speed requires minimal setup. Not a custom HTTP client, not a configuration object, not a builder — just a single function you wrap around the fromJson call you already have.
Every failure carries its source. Ambiguous crashes halt development; triage must be instantaneous. The endpoint name, expected type, original exception, and exact stack trace are packed into one typed object.
Zero dependencies. Version conflicts stall builds. The core must be completely isolated: pure Dart, working identically across Flutter, CLI, and server code.

The API

The whole public surface:

import 'package:json_shield/json_shield.dart';

// Single object. T is inferred from the factory tear-off.
final user = guard.decode(User.fromJson, response.data,
    context: 'users_me_get');

// Top-level array.
final orders = guard.decodeList(Order.fromJson, response.data,
    context: 'orders_list');

Failure handling:

try {
  final orders = guard.decodeList(Order.fromJson, response.data,
      context: 'orders_list');
} on DecodeListException catch (e) {
  // e.total = 100, e.errors = [(index: 17, error: ...), ...]
  report(e); // "3/100 failed. #17: ...; #41: ...; #98: ..."
} on DecodeException catch (e) {
  // Broken array shape (envelope, null body) or single-object failure.
  report(e); // e.context, e.expected, e.cause, e.causeTrace
}

That's it: two methods, two exception types, one flag. One file, ~200 lines, zero dependencies. pub.dev · GitHub

Decisions worth defending

Four choices look wrong at first glance. Each is deliberate.

Shape checks run before your factory

null body, a List where an object is expected, a primitive, a pagination envelope on an array endpoint — all rejected with DecodeException(expected: ...) before fromJson is ever invoked. Your factory only sees a Map<String, dynamic>; the cryptic subtype error class of crashes is gone, replaced by a named expectation. If the factory itself throws — age came back as a string — the exception is wrapped with the original cause and its stack trace preserved, not swallowed.

Lists are traversed fully, failures aggregated

Fail-fast decoding reports element #0, you fix it, deploy, and meet element #41. decodeList never stops: it decodes every element, collects every failure with its index, and throws one DecodeListException carrying all of them. One run yields the complete map of a broken contract — and the pattern inside it. Identical cause on every index? The backend changed the schema. Three scattered indices? Dirty rows in their database. That distinction is a one-glance read in the aggregate and invisible in fail-fast.

The deliberate flip side: it still throws on a single bad element. Silently skipping broken rows and rendering the rest hides data loss from you and your users; if you want partial rendering, catch the aggregate and decide — the decoder won't decide for you.

Payloads are redacted by default

DecodeException.rawData — the actual JSON that failed — is null and the console stays silent unless you flip guard.verbose = true in a debug entry point; with the flag on, every failure is also printed the moment it happens, one line per broken element. Backwards from every logging library, deliberate here: response payloads contain user data, and exceptions flow into crash reporters. After years of wiring gateways into commerce apps, payloads carrying card and customer data are not a hypothetical. The failure mode of forgetting the flag had to be "less diagnostic detail," never "PII in Sentry."

The API shrank during development

Earlier iterations had one/many combinator functions, a unified reified-generics dispatcher, string-input variants, tryDecode result types, and an encode side. All cut. Every additional entry point is another decision at the call site and another way to hold the tool wrong; the two survivors cover the actual production need — decoding a response you just received. The single least-obvious survivor is the argument order, (fromJson, json): factory first reads as "decode as User this data" and keeps the tear-off — the thing that determines the type — in the position your eye checks first.

What it refuses to do

No HTTP, no retries, no schema validation, no code generation. A decoding guard that grows a network client stops being auditable in one sitting — and being auditable in one sitting is a feature: the entire implementation is a single file you can read before trusting it with production traffic.

Next in the series

A growing share of the code calling any package is written by AI assistants that have never seen its repository. Part 2 covers what that changes for package authors: the four artifacts that reach a consumer's AI, the one that steers a contributor's agent, and how to write both so models stop hallucinating your API.

json_shield: pub.dev · GitHub. Issues and API roasting welcome — the surface is frozen pre-1.0, but frozen by discussion, not by ego.