Architecture 

The short version 

The extension's whole job is array shaping: it takes rich TYPO3 domain objects and turns them into plain, JSON-compatible arrays — with a stable, frozen output contract. Object resolution is done by the TYPO3 Core (RecordFactory); key mapping, field ordering and value shaping are done here. That split is deliberate: it is what allows the same code to run on TYPO3 13 and 14 without version forks.

The pipeline 

TypoScript data processor (Site Set: lib.contentBlock)
 └─ nb-content-blocks-json  (ContentBlocksJsonDataProcessor)
     ├─ RecordFactory::createResolvedRecordFromDatabaseRow()   [Core]
     │    DB row → rich objects (Record, FileReference, TypolinkParameter,
     │    DateTimeImmutable, LazyRecordCollection, ...)
     └─ RecordArrayBuilder::build()
          ├─ strip system fields (uid, pid, colPos, CType, ...)
          ├─ map columns → Content Block field identifiers
          │    (tx_myext_field → my_field, via ContentBlocksIdentifierMapper)
          ├─ dispatch ModifyArrayRecursiveToArrayEvent per field (deprecated)
          ├─ strings → FieldValueTransformerChain
          │    (PasswordBlanker, RichtextParser — schema-driven)
          ├─ everything else → NormalizerChain
          │    first registered normalizer with supports() === true wins;
          │    unknown types → UnknownTypeNormalizer (null + debug log)
          └─ ksort
 └─ headless.php include (optional, per Content Block)
 └─ sub data processors (optional, TypoScript dataProcessing.)

nb-container-json (ContainerJsonDataProcessor) follows the same shape for EXT:container children: it fetches the children of a container column and renders each through the same RecordArrayBuilder.

Building blocks 

Why normalizers (and not one big converter) 

Before the 2026-08 rewrite, one class held a giant switch (true) with instanceof chains over ContentBlocks internals, makeInstance() everywhere, and version hacks (property_exists(...)) to construct those internals in tests. The rewrite (see the design record) replaced it with a normalizer registry — the Symfony Serializer pattern, hand-rolled without the dependency:

• each normalizer is small and independently testable,
• site packages can add their own via DI tag (nb_headless.normalizer),
• field metadata comes from the Core Schema API (TcaSchemaFactory), which ships in TYPO3 13 and 14 — the version hacks disappeared because the code stopped constructing ContentBlocks internals.

ContentBlocks stays a hard dependency for exactly two things that have no Core equivalent: the identifier mapping (dropping it would change every consumer's JSON contract) and resolving the Content Block folder (headless.php, headless.yaml).

Design principles 

• The JSON contract is the product. Output shapes are frozen by characterization tests (ContentBlocksJsonDataProcessorCharTest) that assert the complete JSON per fixture record. A refactor must not change them; a contract change is a deliberate, documented decision.
• Never break the response. Unknown value types become null with a debug log entry; a missing file becomes an __errorMessage entry in place — the page still renders.
• Config before code. What used to need a headless.php (image variants) is now declarative (headless.yaml + TypoScript override). headless.php remains as an escape hatch.

Extension points 

When several extension points could solve a problem, prefer the most declarative one (image variants over headless.php, transformer over event).