DEV Community: David Evdoshchenko

How I Built an llms.txt Generator That Actually Works at Scale

David Evdoshchenko — Tue, 12 May 2026 08:16:00 +0000

This is the technical companion to my I Built an llms.txt Generator, Showed It to the Creator of the Standard, and Had to Rewrite Everything — the human side is there, here's just the engineering.

The goal: automatically generate a proper llms.txt hierarchy for any website — not a flat index of summaries, but a structured set of MD files where semantically related pages are merged into coherent documents. Here's how each layer works and what broke along the way.

The Architecture

Sitemap → Crawler → Embedder → Clusterer → Summarizer → llms.txt + MD files

Five stages. Each runs at a different speed. Each has its own failure modes.

Stage 1: Crawling

Standard crawling with content extraction. The output per page: path, title, clean text.

Pages that fail to crawl are tracked but don't stop the pipeline — a missing page just doesn't contribute to its cluster.

Stage 2: Embeddings + Caching

Each page gets converted to a vector using Gemini's gemini-embedding-001 model.

Vectors are cached in Redis keyed by hostname + model + path. On reprocessing the same site, already-embedded pages are served from cache instantly — no API calls, no cost.

const allCached = await this.cacheService.hmget(
  hashKey,
  allPaths.map(p => `vectors:${p}`)
);
// Cache hits skip embedding entirely

This matters because embeddings are the most parallelizable step and you don't want to redo them on retries or restarts.

Stage 3: K-Means Clustering with Cosine Similarity

Pages cluster by semantic meaning, not URL structure. Two pages about the same concept with different URL paths end up in the same cluster. Three pages under /payments/checkout/ that cover different topics end up in different clusters.

K-means implemented directly in TypeScript — no external ML libraries. Cosine similarity as the distance metric, not Euclidean — cosine works much better for high-dimensional embedding vectors.

private kMeans(vectors: number[][], k: number, maxIterations = 100): number[] {
  const dim = vectors[0].length;
  let centroids = vectors.slice(0, k).map(v => [...v]);
  let assignments = new Array<number>(vectors.length).fill(0);

  for (let iter = 0; iter < maxIterations; iter++) {
    const newAssignments = vectors.map((v) => {
      let minDist = Infinity, nearest = 0;
      for (let c = 0; c < centroids.length; c++) {
        const dist = 1 - this.cosineSimilarity(v, centroids[c]);
        if (dist < minDist) { minDist = dist; nearest = c; }
      }
      return nearest;
    });

    const changed = newAssignments.some((a, i) => a !== assignments[i]);
    assignments = newAssignments;
    if (!changed) break;

    centroids = Array.from({ length: k }, (_, c) => {
      const members = vectors.filter((_, i) => assignments[i] === c);
      if (members.length === 0) return centroids[c];
      const sum = new Array<number>(dim).fill(0);
      for (const v of members) {
        for (let d = 0; d < dim; d++) sum[d] += v[d];
      }
      return sum.map(s => s / members.length);
    });
  }
  return assignments;
}

The number of clusters is dynamic — determined by the actual content distribution, not a fixed parameter.

Stage 4: Cluster Summarization with Context Caching

Each cluster goes through a two-phase generation process.

Phase 1 — Structure: One LLM call that returns the section name, description, and how many output MD pages to generate. The LLM decides whether to merge source pages, split them, or skip irrelevant ones — I don't impose that from outside.

Phase 2 — Content: One call per output page, generating filename, title, summary, and full markdown content.

The Context Caching Problem

Naive implementation: send all cluster page content as context on every call. For a cluster generating 5 MD files, you pay for those input tokens 5 times.

Fix: Gemini Context Caching. Upload the cluster content once, get a cache reference, use it for all subsequent calls within the cluster.

private async createCacheStrategy(
  model: string,
  systemInstruction: string,
  pagesText: string,
  baseConfig: Record<string, unknown>
) {
  try {
    const cached = await this.ai.caches.create({
      model,
      config: {
        ttl: '600s',
        systemInstruction,
        contents: `Pages:\n${pagesText}`
      }
    });

    return {
      config: { ...baseConfig, cachedContent: cached.name },
      getContents: (prompt: string) => prompt,
      dispose: async () => {
        await this.ai.caches.delete({ name: cached.name }).catch(() => {});
      },
      refreshIfNeeded: () => {
        void this.ai.caches.update({
          name: cached.name,
          config: { ttl: '600s' }
        }).catch(() => {});
      }
    };
  } catch (err) {
    // Gemini requires minimum token count for caching.
    // Small clusters fall back to inline context.
    if (err instanceof ApiError && err.status === 400
        && err.message.includes('min_total_token_count')) {
      return {
        config: { ...baseConfig, systemInstruction },
        getContents: prompt => `Pages:\n${pagesText}\n\n${prompt}`,
        dispose: () => Promise.resolve(),
        refreshIfNeeded: () => {}
      };
    }
    throw err;
  }
}

The cache TTL is 600 seconds. For large clusters that take longer, refreshIfNeeded() is called after each page generation to reset the TTL before it expires.

The cache is deleted in the finally block after the cluster finishes — no leaking paid cache slots.

Stage 5: Buffers Between Layers

Crawling, embedding, and summarizing run at completely different speeds. The crawler is fast. The embedder processes in batches. The summarizer is slow — LLM calls take seconds to minutes each.

Wire them together naively and they block each other. The crawler piles up thousands of pages while the embedder waits. The summarizer starves waiting for embeddings to flush.

Solution: in-memory buffers between each layer. Each stage writes to its output buffer and reads from the previous stage's buffer. Concurrency is controlled independently per stage via the AIMD queue.

The AIMD Queue

The core reliability mechanism. AIMD — Additive Increase Multiplicative Decrease — is the same algorithm TCP uses for congestion control, applied to LLM API calls.

private onSuccess(): void {
  this.successStreak++;
  if (this.successStreak >= this.concurrency) {
    const next = this.concurrency + 1;
    this.concurrency = this.maxConcurrency !== null
      ? Math.min(next, this.maxConcurrency)
      : next;
    this.successStreak = 0;
  }
}

private onRateLimit(kind: ErrorKind): void {
  const prev = this.concurrency;
  this.concurrency = Math.max(Math.floor(this.concurrency / 2), 1);
  this.successStreak = 0;
}

Rules:

Start at concurrency = 1
After a full successful round: concurrency += 1
On 429 or 503: concurrency = floor(concurrency / 2)
Failed tasks re-enqueue at the front of the queue, not the back — so they're not starved behind new work

For 429 responses specifically, the queue reads the actual delay from Google's google.rpc.RetryInfo response header instead of using a fixed backoff:

private static extractRetryDelayMs(err: unknown): number {
  const errObj = err as Record<string, unknown>;
  const details = (errObj?.error as Record<string, unknown>)
    ?.details as Record<string, unknown>[] | undefined;
  const retryInfo = details?.find(
    d => d['@type'] === 'type.googleapis.com/google.rpc.RetryInfo'
  );
  const retryDelayStr = retryInfo?.['retryDelay'] as string | undefined;
  if (retryDelayStr) {
    const parsed = parseFloat(retryDelayStr);
    if (!isNaN(parsed)) return parsed * 1000;
  }
  return 15000; // fallback
}

If the API says wait 15 seconds, wait 15 seconds. Not 1 second (too aggressive), not 60 seconds (too slow).

Max 16 attempts per task. 5 minute timeout per call. After that, permanent failure.

Typed LLM Exceptions

LLM failures aren't all the same. Treating them identically means either retrying things that can't succeed or giving up on things that would succeed on the next attempt.

// Response isn't valid JSON at all
class LlmJsonValidationException extends LlmBaseException {}

// Asked for N summaries, got M
class LlmResponseCountMismatchException extends LlmBaseException {
  constructor(
    message: string,
    public readonly expected: number,
    public readonly received: number,
    public readonly invalidResponse: unknown,
    attemptNumber: number
  ) { ... }
}

// JSON valid but missing required fields
class LlmInvalidSummaryFieldException extends LlmBaseException {}

Each type carries the context needed to decide the retry strategy. LlmResponseCountMismatchException includes what was expected vs received — useful for adjusting the prompt on retry.

Resumable Processing

Tasks have a max attempt count. After 16 failures, a task is dropped from the queue permanently.

But the order stays in the database. The user can restart it from the frontend.

And because all intermediate results — vectors, generated MD files — are cached in Redis, restarting picks up where it left off. Pages that already embedded don't re-embed. Clusters that already generated their MD files don't regenerate. Only the failed work gets retried.

This matters because a large order can fail partway through due to external issues (API downtime, budget limits, the German spaces problem described below) and you don't want to throw away hours of completed work.

The German Spaces Problem

For reasons I still don't fully understand, Gemini sometimes responds to German-language content with a valid response followed by approximately 2,000,000 spaces. This hits max token limits and the call crashes.

It's not consistent. It's not reproducible on demand. It just happens sometimes with German text.

The handling: 3 retries, then permanent failure for that task. The order remains restartable. The resumable processing above means retrying the order doesn't cost anything for already-completed work.

What the Output Looks Like

# docs.stripe.com
Comprehensive documentation for integrating Stripe payments...

## Account Setup And Management
- [Account Setup Overview](/account-setup-and-management/overview.md): ...

## Payments
...

ZIP archive: llms.txt at root, subfolders with the .md files.

Same site, both strategies side by side:

Flat strategy output — one summary per URL
Clustered strategy output — semantic clusters, MD files, ZIP

Stripe's ~4,000 pages: under an hour on a 4-core / 8GB server.

What's Not Solved Yet

Multilingual sites. When Stripe added German translations their URL count jumped from ~3,500 to ~4,300. The generator processed everything and produced German MD files for what should be an English documentation site. Planned fix: URL pattern filter as an order parameter — you specify which URL patterns to include, the crawler respects it.

Custom prompts. The summarization prompt is currently fixed. Making it a user parameter would allow different output styles — technical reference, narrative guides, API docs — without changing the pipeline.

An Observation About the Future

There are already tools that generate complete human-readable documentation sites from markdown source files.

This suggests an interesting workflow inversion:

Generate llms.txt + structured markdown (the AI-oriented layer)
Generate the human-facing website from those same markdown files

The markdown becomes the source of truth. Write once, publish twice — one version for humans, one for AI agents.

Try It

Generator: llmstxtgenerator.svcpool.com. Free tier up to 5,000 pages. API available.

Full spec: llmstxt.org.

I Built an llms.txt Generator, Showed It to the Creator of the Standard, and Had to Rewrite Everything

David Evdoshchenko — Tue, 12 May 2026 08:15:00 +0000

This is a follow-up to my previous post — I shipped v1, got feedback from the creator of the standard, and had to rethink everything.

I'm not going to pretend I had a plan. I didn't.

There's a new standard called llms.txt — a file you place in your site root to help AI agents navigate your content. Think of it as robots.txt for AI agents: instead of telling crawlers what to ignore, it tells agents how to understand your site.

I saw other generators producing it. I built one too, shipped it, and thought I was done.

Then I talked to Jeremy Howard — the creator of the standard — and discovered I had fundamentally misunderstood what llms.txt is supposed to be. And then things got complicated.

Version 1: Copying What Everyone Else Was Doing

The pattern every generator was producing:

- [Page Title](https://example.com/page): AI-generated summary.
- [Another Page](https://example.com/other): AI-generated summary.

One URL → one summary. I did the same. I called this the Flat strategy and shipped it. It's still in the generator because people ask for it. But I no longer think it's what llms.txt is actually for.

The Conversation That Changed Everything

About six weeks after shipping I posted in the llms.txt Discord and asked Jeremy Howard directly.

Me:

For a site like Stripe with 4,000 pages, how do you balance curation vs completeness? If you curate down to 20 pages, an agent asking about webhook retries won't find the answer. If you include everything, it's just noise.

Jeremy Howard (source):

"Yeah it's actually a lot of work - it's not just writing an llms.txt, but writing complete agent-oriented docs. It's basically like a parallel web - one designed for AI! An llms.txt is just AI's index.html replacement - it contains links to other md pages, which themselves can have links."

And then the part that really got me — he wasn't just describing a different structure. He was saying that llms.txt shouldn't be generated automatically at all. It should be carefully curated by humans who understand their site.

I sat with that for a bit.

On one hand, he's right. On the other hand — Stripe has 4,000 pages. Nobody is writing those MD files by hand. And weather.com has 1,140,000 URLs. The math doesn't work for human curation at scale.

So I decided to try anyway. If it can't be done automatically, let's see how close we can get.

Me (source):

"That changes everything. The 'curation vs completeness' tension I was worried about disappears when you have progressive disclosure through a hierarchy."

So I went and built Version 2.

What Version 2 Actually Required

The vision was simple: semantically group related pages, synthesize each group into one MD file. An agent gets 30 focused documents instead of 4,000 individual pages.

The reality was five separate engineering problems, each hiding behind the previous one.

Problem 1 — Context windows. To group pages by meaning you need to read them. 4,000 pages of full text doesn't fit in any LLM context window. Solution: embeddings + k-means clustering. Each page becomes a vector, similar pages cluster together, the LLM only ever sees one cluster at a time.

Problem 2 — Money. Each LLM call was sending the same cluster content over and over as input tokens. For a cluster generating 5 MD files I was paying for those pages 5 times. Solution: Gemini Context Caching. Upload the cluster content once, reuse the cached reference for all subsequent calls within that cluster.

Problem 3 — Layers at different speeds. Crawling, embedding, and summarizing run at completely different speeds. Wire them together naively and they block each other — the crawler piles up work while the summarizer starves. Solution: in-memory buffers between each layer, with independent concurrency control per layer.

Problem 4 — The LLM is unreliable. At scale, everything fails eventually. Gemini returns 429, 503, valid JSON with the wrong number of items, invalid JSON, or just times out after 4 minutes. Solution: typed exception hierarchy for LLM failures, AIMD queue with proper backoff that reads actual retry-after values from Google's API instead of guessing.

Problem 5 — German spaces. For reasons I still don't fully understand, Gemini sometimes responds to German-language content with a valid response followed by approximately 2,000,000 spaces. This hits max token limits and crashes. Solution: 3 retries, then the task is dropped — but the order stays in the database and can be restarted from the frontend. Intermediate results are cached in Redis so restarting picks up where it left off without re-spending tokens.

Each problem only became visible after solving the previous one. That's how it goes.

The Unsolved Problem: Multilingual Sites

When I started, Stripe's docs had ~3,500 URLs. Then they added German translations and it jumped to ~4,300. The generator processed everything and started producing German-language MD files for what should be an English documentation site.

There's no universal logic to detect canonical single-language content from a sitemap. Every site has its own URL scheme. Planned fix: a URL pattern filter as an order parameter — you specify which patterns to include, the crawler respects it.

An Observation About the Future

While building this I noticed something: there are already tools that generate complete human-readable documentation sites from markdown source files.

This opens up an interesting workflow:

Generate llms.txt + structured markdown (the AI layer)
Generate the human-facing website from those same markdown files

The markdown becomes the source of truth. Write once, publish twice — one version for humans, one for AI agents.

Epilogue

I don't know if this will ever make me a dollar.

But since building this, people started reaching out on LinkedIn. Interview invitations started coming in. I talked to Microsoft today.

And I find it genuinely funny when I get coding assessments that ask me to build a notification service — clean code, scalable architecture, perfect database design, dockerized, fully tested — in 3 days.

I spent several months building something like what you just read about, and I'm still not sure I got it right.

Those 3-day assessments make me laugh.

*Want to understand how this actually works under the hood — embeddings, clustering, context caching, the AIMD queue? I wrote a separate technical deep-dive: How I Built an llms.txt Generator That Actually Works at Scale

The generator is at llmstxtgenerator.svcpool.com. Free tier up to 5,000 pages.

Full spec: llmstxt.org.

Launching another one LLMs.txt Generator! 🚀

David Evdoshchenko — Sat, 14 Mar 2026 14:03:10 +0000

Built a tool that automatically generates llms.txt files for websites using AI and really for free (up to 5000 pages under one domain).

What it does:

✅ Helps LLM models better understand your site's content
✅ Automatic crawling and page processing
✅ Support for multiple AI models
✅ From URL to ready llms.txt in minutes

Tech stack: SvelteKit, NestJS, TypeScript, WebSocket for real-time updates.

🕸️ Web version: https://llmstxtgenerator.svcpool.com
👊 API as well: https://llmstxtgenerator.svcpool.com/api

Would love to hear your thoughts!

I had to build my own Symfony validation bundle because no existing one fits my requirements

David Evdoshchenko — Wed, 11 Mar 2026 22:02:22 +0000

Long story short
The Problem
The Idea
The Solution
Quick Examples
- Example 1
- Example 2
What's the result?
The Full Story

Long story short

I created a bundle for request validation with JSON Schema because no existing "schema-first" validator fit my requirements. Now I just attach a JSON file to a route and get everything at once: validation, DTO mapping, and OpenAPI documentation from a single source of truth.

The Problem

Most validation solutions that can generate API documentation from code (in the Symfony world I mostly mean FOSRestBundle and API Platform) assume that your business logic is:

Well defined and relatively stable
Close to a classic CRUD model (or CRUD with small deviations)
Exposed via clean, REST-style endpoints that you fully control

In other words, they assume your application defines the contract and the outside world adapts to it.

But in many real projects it is the opposite: the API contract is defined somewhere else (legacy frontend, external systems, partners), and you have to adapt to that contract. That is where problems start.

Here is a simplified example. The API expects this payload:

{
  "type": "company",
  "user": {
    "name": "John",
    "email": "john@example.com",
    "company": {
      "name": "Acme"
    }
  }
}

With the following rules:

If type = "company" then user.company.name is required
If type = "person" then user.company must be absent

Is this the most elegant API design? Probably not. But imagine a company with 2000 people and a frontend written years ago that sends exactly this structure. You cannot just redesign everything because you do not like the shape of the JSON.

Now, what does the "ideal" Symfony validation setup suggest here?

class UserDto
{
    #[Assert\NotBlank]
    public string $name;

    #[Assert\Valid]
    public ?CompanyDto $company;
}

This does not express the conditional logic "company.name is required when type = company". To implement this you usually end up with one of the following:

Custom constraint with its own validator
Manual validation logic in the controller or a service
Custom normalizer / denormalizer with additional checks

Then another question appears: how do you forbid extra properties that are not defined in UserDto? For a long time you simply could not. In newer Symfony versions you can write something like:

#[MapRequestPayload(
    serializationContext: ['allow_extra_attributes' => false]
)]

#[MapQueryString(
    serializationContext: ['allow_extra_attributes' => false]
)]

Whether this works for query parameters depends on the exact types and context. For headers this approach does not work at all.

You might ask: why be so strict? Why not just ignore extra parameters? Because in real life this often leads to subtle bugs. A typical scenario: you had a query parameter offset and later renamed it to page for consistency with other APIs. Some client code still sends offset. If you ignore unknown parameters, the request "works", but returns the wrong page. You then spend time debugging something that could have been caught immediately.

With strict validation the client would get a clear error about an unknown parameter, and the problem would be visible right away.

My personal view is that even though an API has no visual UI, it still has UX. Clients should receive clear, precise error messages, not a generic "Provided data is incorrect". Detailed validation errors are also in the interest of the backend team: fewer support tickets, less time spent guessing what went wrong on the client side.

The Idea

The kind of validation I needed has actually existed for years, just not in the form of typical Symfony validators. I am talking about the JSON Schema standard:

https://json-schema.org/specification

JSON Schema is a declarative language for defining structure and constraints for JSON data

It is designed exactly for problems like the ones above (and much more complex ones):

Conditional rules based on other fields
Nested, deeply structured data
Strict control over allowed and forbidden properties

So the idea was simple: instead of forcing my API contract into DTO classes and annotations, let Symfony validate incoming requests against a JSON Schema that fully describes the contract.

In other words, make Symfony request validation schema-first, with JSON Schema as the single source of truth.

The Solution

The good news was that I did not need to implement JSON Schema myself. There was already a solid PHP implementation:

https://opis.io/json-schema/

The library takes a valid JSON Schema and any input data, validates the data against the schema and either:

returns the data (when everything is valid), or
returns a structured list of validation errors.

From there, the rest was mostly integration work:

Make it convenient to plug this validation into a Symfony project
Wire it into the request lifecycle
Provide a way to map validated data into DTOs when needed
Integrate with Nelmio so that OpenAPI documentation is generated from the same schemas

Below I will show a couple of short examples. In the "The Full Story" section I describe how I removed duplication between validation attributes and documentation, and how the bundle ended up solving both validation and API specification generation from a single source of truth: the JSON Schema files.

Quick Examples

Example 1
Example 2

The schema

{
    "$schema": "https://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "query": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
        },
        "headers": {
            "type": "object",
            "properties": {
                "authorization": {
                    "type": "string",
                    "description": "Bearer token for authentication",
                    "pattern": "^Bearer .+",
                    "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ6..."
                },
                "x-api-version": {
                    "type": "string",
                    "description": "API version",
                    "enum": ["v1", "v2"],
                    "example": "v1"
                },
                "content-type": {
                    "type": "string",
                    "description": "Request content type",
                    "enum": ["application/json"],
                    "example": "application/json"
                }
            },
            "additionalProperties": true
        },
        "body": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 100,
                    "description": "User's full name",
                    "example": "Jane Smith"
                },
                "email": {
                    "type": "string",
                    "format": "email",
                    "description": "User's email address",
                    "example": "john.doe@example.com"
                },
                "age": {
                    "type": "integer",
                    "minimum": 21,
                    "maximum": 100,
                    "description": "User's age (optional)",
                    "example": 30
                }
            },
            "required": ["name", "email"],
            "additionalProperties": false
        }
    }
}

Example 1: validation using the built-in request object

#[OA\Post(
    operationId: 'validateUser',
    summary: 'Validate user',
)]
#[Route('/user', name: '_example_validation_user', methods: ['POST'])]
public function validateUser(#[MapRequest('./user-create.json')] ValidatedRequest $request): JsonResponse
{
    $payload = $request->getPayload();
    $body    = $payload->getBody();

    return $this->json([
        'success' => true,
        'message' => 'User data is valid',
        'data'    => [
            'name'  => $body->name,
            'email' => $body->email,
            'age'   => $body->age ?? null,
        ],
        'example' => 'This uses ValidatedRequest (standard way)',
    ], 200);
}

Example 2: validation using a custom DTO (via ValidatedDtoInterface)

#[OA\Post(
    operationId: 'createProfile',
    summary: 'Create profile',
)]
#[Route('/profile', name: '_example_validation_profile', methods: ['POST'])]
public function createProfile(#[MapRequest('./user-create.json')] UserApiDtoRequest $profile): JsonResponse
{
    return $this->json([
        'success' => true,
        'message' => 'Profile created successfully',
        'profile' => [
            'name'  => $profile->name,
            'email' => $profile->email,
            'age'   => $profile->age,
        ],
        'note'    => sprintf('This demonstrates DTO auto-injection: MapRequestResolver calls %s::fromPayload() automatically', UserApiDtoRequest::class),
    ], 201);
}

What's the result?

Focused solution: instead of reinventing the wheel, the bundle fills a specific gap that existing Symfony tools do not cover well (schema-first request validation).
Less duplication: you no longer have to mirror the same rules in DTO constraints, controllers and OpenAPI annotations.
Automatic sync: Nelmio builds documentation from the same JSON Schema files that are used for validation, so your docs always match the real behavior.
Contract-centric design: the entire API contract lives in clean JSON files rather than being scattered across PHP attributes and PHP classes.

If you were looking for a way to validate requests without creating a large number of redundant DTO classes and annotations, this bundle is designed for that use case:

The Full Story

This article is the short, focused version of the story: what the bundle does and how to start using it. If you want the long version with all the scars and details, I wrote a separate, much bigger post.

In that post I go through:

how the bundle was born in a very messy real project, not in a greenfield demo
why classic DTO + Assertions validation did not survive 500+ routes
how JSON Schema became the single contract language for backend, frontend and docs
how the bundle glues Symfony, Opis JSON Schema and Nelmio together

You can read the full story here (starting from The Full Story section):

https://outcomer.hashnode.dev/symfony-bundle-that-validates-anything-and-everything#the-full-story

I built a Symfony bundle that validates anything and everything.

David Evdoshchenko — Sun, 08 Mar 2026 13:49:08 +0000

Long story short

I created a bundle for request validation via JSON Schema because I was fed up with the lack of a simple "schema-first" validator. Now, I just attach a JSON file to a route, and everything - validation, DTO mapping, and OpenAPI documentation - works out of the box.

Feel free to ask me whatever relevant to topic via comments here;

The Pain Point

I didn't set out to build my own bundle. I had a simple task: validate an incoming request against specific conditions.
Sounds basic, right? But when I looked for a solution, I found that the modern Symfony world is stuck in one specific pattern:

create a DTOs;
write a ton of assertions (Annotations/Attributes);
if the structure is complex or dynamic-suffer and write custom normalizers;

I searched everywhere but couldn't find a straightforward way to say: "Here is my JSON, here is my schema, just check them and give me an object." Instead, I was forced to create mountains of boilerplate that I didn't need.

Why DTO + Assertions isn't always the answer

The classic approach with assertions in PHP classes works fine for simple forms or strictly structured data. But as soon as you deal with deep nesting or requirements that don't play well with normalization - it's much easier to define the requirements once in the JSON Schema standard. Otherwise, you end up duplicating logic - firstly in code, then in docs.

I wanted flexibility. I wanted to use a standard that everyone understands - from frontend developers to QA engineers.

Solution

How I solved it: I built a bundle that makes JSON Schema a "first-class citizen" in Symfony. Now, instead of describing validation rules in PHP code, I simply point to a schema.

The bundle allows you to validate data either into a built-in DTO (which always contains validated path, query, headers, and body) or into your own custom class, provided it implements the ValidatedDtoInterface.

Example 1: Validation into the built-in ValidatedRequest

#[OA\Post(
    operationId: 'validateUser',
    summary: 'Validate user',
)]
#[Route('/user', name: '_example_validation_user', methods: ['POST'])]
public function validateUser(#[MapRequest('./user-create.json')] ValidatedRequest $request): JsonResponse
{
    $payload = $request->getPayload();
    $body    = $payload->getBody();

    return $this->json([
        'success' => true,
        'message' => 'User data is valid',
        'data'    => [
            'name'  => $body->name,
            'email' => $body->email,
            'age'   => $body->age ?? null,
        ],
        'example' => 'This uses ValidatedRequest (standard way)',
    ], 200);
}

Example 2: Validation into your own DTO (via ValidatedDtoInterface)

#[OA\Post(
    operationId: 'createProfile',
    summary: 'Create profile',
)]
#[Route('/profile', name: '_example_validation_profile', methods: ['POST'])]
public function createProfile(#[MapRequest('./user-create.json')] UserApiDtoRequest $profile): JsonResponse
{
    return $this->json([
        'success' => true,
        'message' => 'Profile created successfully',
        'profile' => [
            'name'  => $profile->name,
            'email' => $profile->email,
            'age'   => $profile->age,
        ],
        'note'    => sprintf('This demonstrates DTO auto-injection: MapRequestResolver calls %1$s::fromPayload() automatically', UserApiDtoRequest::class),
    ], 201);
}

What's the result?

I didn't "reinvent the wheel"; I simply filled a gap in the ecosystem;
No more duplicate work: No more writing endless #[Assert\NotBlank], #[Assert\Type("string")], etc;
Automatic Sync: Nelmio picks up the schema from the same file - your documentation never lies;
Contract-Centric: The entire API contract lives in clean JSON files rather than being scattered across PHP attributes;

If you, like me, were looking for a way to validate requests like a human being without creating dozens of redundant classes - here is the solution:

I had to build my own Symfony validation bundle because no existing one fits my requirements.

David Evdoshchenko — Thu, 05 Mar 2026 19:53:54 +0000

UPDATE: I have completely rewritten this guide to focus on a more pragmatic approach.

My original article discussed the challenges of Symfony/OpenAPI validation, but since then, I've built a dedicated tool that solves this by using JSON Schema as the single source of truth.

You can find the improved, "no-boilerplate" version of this article here: https://dev.to/outcomer/i-built-a-symfony-bundle-that-validates-anything-and-everything-4nah