diff --git a/modules/json_form_widget/README.md b/modules/json_form_widget/README.md
index fbfe3e3a35..51d4748d63 100644
--- a/modules/json_form_widget/README.md
+++ b/modules/json_form_widget/README.md
@@ -1,37 +1,100 @@
+## High level
+
+```mermaid 
+sequenceDiagram
+  participant FormBuilder
+  participant FieldTypeRouter
+  participant Element Handlers
+  participant SchemaUiHandler
+
+  loop each $property in $form
+    FormBuilder ->> FieldTypeRouter: getFormElement()
+    FieldTypeRouter ->> Element Handlers: handler functions<br />on helper classes
+    Note over FieldTypeRouter, Element Handlers: Initial build of property<br />Elements
+    Element Handlers ->> FormBuilder: Return default element for $property
+  end
+  
+  FormBuilder ->> SchemaUiHandler: applySchemaUi()
+  Note over FormBuilder, SchemaUiHandler: Now apply SchemaUi to full $form
+  loop each $property
+    SchemaUiHandler ->> SchemaUiHandler: applyOnBaseField()
+    SchemaUiHandler ->> SchemaUiHandler: handlePropertySpec()
+    Note over SchemaUiHandler, SchemaUiHandler: See handlePropertySpec() <br />internals diagram
+  end
+  SchemaUiHandler ->> FormBuilder: Return $form with SchemaUi alterations
+
+```
+
+## The handlePropertySpec() method
+
+As called from withing SchemaUiHandler::applyShemaUi
+
+```mermaid
+sequenceDiagram
+  participant handlePropertySpec
+
+
+```
+
+## The initial build
+
 ```mermaid
 graph TD
   getForm["FormBuilder::getJsonForm()"] --> eachProp["foreach $properties"]
-  subgraph getElements
-    eachProp --> getElement["FieldTypeRouter::getFormElement()"]
-    getElement --> switch[Switch $type]
-    switch --> object{object}
-    
-    object -- true --> handleObject["ObjectHelper::handleObjectElement()"]
-    handleObject --> generateObject["ObjectHelper::generateObjectElement()"]
-    generateObject --> generateProperties["ObjectHelper::generateProperties()"]
-    generateProperties -- recursion --> eachProp
-
-
-    object -- false --> array{array}
-    array -- true --> handleArray["ArrayHelper::handleArrayElement()"]
-    handleArray --> complex{Items are objects?}
-    complex -- no --> buildSimple["ArrayHelper::buildSimpleArrayElement()"]
-    complex -- yes --> buildComplex["ArrayHelper::buildComplexArrayElement()"]
-    buildComplex --> handleObject
-
-    array -- false --> string["string"]
-    string -- true --> handleString["StringHelper::handleStringElement()"]
-    string -- false --> integer["integer"]
-    integer -- true --> handleInteger["IntegerHelper::handleIntegerElement()"]
-    switch --> eachProp
-  end
-  eachProp -->getForm
-  getForm --> applySchemaUi["SchemaUiHandler::applySchemaUi()"]
+  eachProp --> getElement["FieldTypeRouter::getFormElement()"]
+  getElement --> switch[Switch $type]
+  switch --> object{object}
+  
+  object -- true --> handleObject["ObjectHelper::handleObjectElement()"]
+  handleObject --> generateObject["ObjectHelper::generateObjectElement()"]
+  generateObject --> generateProperties["ObjectHelper::generateProperties()"]
+  generateProperties -- recursion --> eachProp
+
+
+  object -- false --> array{array}
+  array -- true --> handleArray["ArrayHelper::handleArrayElement()"]
+  handleArray --> complex{Items are objects?}
+  complex -- no --> buildSimple["ArrayHelper::buildSimpleArrayElement()"]
+  complex -- yes --> buildComplex["ArrayHelper::buildComplexArrayElement()"]
+  buildComplex --> handleObject
 
-  subgraph SchemaUI
+  array -- false --> string["string"]
+  string -- true --> handleString["StringHelper::handleStringElement()"]
+  string -- false --> integer["integer"]
+  integer -- true --> handleInteger["IntegerHelper::handleIntegerElement()"]
+  switch --> eachProp
+  eachProp --> getForm
+```
+
+## Customizing widgets w/SchemaUI
+
+```mermaid
+flowchart-elk TD
+    getForm["FormBuilder::getJsonForm()"] --> applySchemaUi["SchemaUiHandler::applySchemaUi()"]
     applySchemaUi --> eachProp2["foreach schemaUI property"]
     eachProp2 --> applyOnBaseField["SchemaUiHandler::applyOnBaseField()"]
-    eachProp2 --> handlePropertySpec["SchemaUiHandler::handlePropertySpec()"]
+    eachProp2 --> handlePropertySpec
+    subgraph s1["applyOnBaseField()"]
+        applyOnBaseField --> updateWidgets["SchemaUiHandler::updatewidgets()"]
+        updateWidgets --> disableFields["SchemaUiHandler::disableFields()"]
+        disableFields --> addPlaceholders["SchemaUiHandler::addPlaceholders()"]
+        addPlaceholders --> changeFieldDescriptions["SchemaUiHandler::changeFieldDescriptions()"]
+        changeFieldDescriptions --> changeFieldTitle["SchemaUiHandler::changeFieldTitle()"]
+    end
+    subgraph s2["handlePropertySpec"]
+        handlePropertySpec["SchemaUiHandler::handlePropertySpec()"] --> what{"what is it"}
+        what -- array --> eachArrayElement
+        eachArrayElement --> applyOnArrayFields
+        
+        applyOnArrayFields --> eachArrayElementField
+        eachArrayElementField --> inSpec{"Does SchemaUI<br>contain config for<br>this field?"}
+        inSpec -- yes --> handlePropertySpec
+        inSpec -- no --> applyOnBaseFieldRec["SchemaUiHandler::applyOnBaseField()"]
+
+        what -- object --> applyOnObjectFields
+        applyOnObjectFields --> eachObjField["foreach object property in the SchemaUi spec"]
+        eachObjField --> applyOnBaseFieldRec
+        
+    end
 
-  end
 ```
diff --git a/modules/json_form_widget/src/ArrayHelper.php b/modules/json_form_widget/src/ArrayHelper.php
index da2e87bd3e..05900610ce 100644
--- a/modules/json_form_widget/src/ArrayHelper.php
+++ b/modules/json_form_widget/src/ArrayHelper.php
@@ -475,4 +475,5 @@ public static function trimParents(array &$parents, int $element_index): void {
     $offset = 0 - (count($parents) - $ei_position);
     \array_splice($parents, $offset);
   }
+
 }
diff --git a/modules/json_form_widget/src/FormBuilder.php b/modules/json_form_widget/src/FormBuilder.php
index 0eef2582f6..38f2771117 100644
--- a/modules/json_form_widget/src/FormBuilder.php
+++ b/modules/json_form_widget/src/FormBuilder.php
@@ -68,7 +68,7 @@ public function __construct(
     SchemaRetriever $schema_retriever,
     FieldTypeRouter $router,
     SchemaUiHandler $schema_ui_handler,
-    LoggerInterface $loggerChannel
+    LoggerInterface $loggerChannel,
   ) {
     $this->schemaRetriever = $schema_retriever;
     $this->router = $router;
diff --git a/modules/json_form_widget/src/Plugin/Field/FieldWidget/JsonFormWidget.php b/modules/json_form_widget/src/Plugin/Field/FieldWidget/JsonFormWidget.php
index 57a632e976..3c260f3a6f 100644
--- a/modules/json_form_widget/src/Plugin/Field/FieldWidget/JsonFormWidget.php
+++ b/modules/json_form_widget/src/Plugin/Field/FieldWidget/JsonFormWidget.php
@@ -3,14 +3,14 @@
 namespace Drupal\json_form_widget\Plugin\Field\FieldWidget;
 
 use Drupal\Core\Entity\FieldableEntityInterface;
+use Drupal\Core\Field\FieldDefinitionInterface;
 use Drupal\Core\Field\FieldItemListInterface;
 use Drupal\Core\Field\WidgetBase;
 use Drupal\Core\Form\FormStateInterface;
 use Drupal\json_form_widget\FormBuilder;
+use Drupal\json_form_widget\ValueHandler;
 use Symfony\Component\DependencyInjection\ContainerInterface;
-use Drupal\Core\Field\FieldDefinitionInterface;
 use Symfony\Component\HttpFoundation\RequestStack;
-use Drupal\json_form_widget\ValueHandler;
 
 /**
  * Plugin implementation of the 'json_form_widget'.
@@ -82,7 +82,7 @@ public function __construct(
     array $third_party_settings,
     FormBuilder $builder,
     ValueHandler $value_handler,
-    RequestStack $request_stack
+    RequestStack $request_stack,
   ) {
     parent::__construct($plugin_id, $plugin_definition, $field_definition, $settings, $third_party_settings);
     $this->builder = $builder;
diff --git a/modules/json_form_widget/src/SchemaUiHandler.php b/modules/json_form_widget/src/SchemaUiHandler.php
index 57d20ca5e4..b8e67532f6 100644
--- a/modules/json_form_widget/src/SchemaUiHandler.php
+++ b/modules/json_form_widget/src/SchemaUiHandler.php
@@ -173,7 +173,7 @@ public function applyOnBaseField(mixed $spec, array $element) {
       $element = $this->changeFieldDescriptions($spec->{"ui:options"}, $element);
       $element = $this->changeFieldTitle($spec->{"ui:options"}, $element);
       if (isset($spec->{"ui:options"}->hideActions)) {
-        // $element = $this->flattenArrays($spec->{"ui:options"}, $element);
+        $element = $this->flattenArrays($spec->{"ui:options"}, $element);
       }
     }
     return $element;
@@ -194,13 +194,18 @@ public function flattenArrays(mixed $spec, array $element) {
     unset($element['actions']);
     $default_value = [];
     foreach ($element[$spec->child] as $key => $item) {
-      ArrayHelper::flattenArrayElementFieldset($item);
       $default_value = array_merge($default_value, $this->formatArrayDefaultValue($item));
       if ($key != 0) {
         unset($element[$spec->child][$key]);
       }
     }
-    $element[$spec->child][0]['#default_value'] = $default_value;
+
+    if (isset($element[$spec->child][0]['field'])) {
+      $element[$spec->child][0]['field']['#default_value'] = $default_value;
+    }
+    else {
+      $element[$spec->child][0]['#default_value'] = $default_value;
+    }
     return $element;
   }
 
@@ -211,6 +216,9 @@ private function formatArrayDefaultValue($item) {
     if (!empty($item['#default_value'])) {
       return [$item['#default_value'] => $item['#default_value']];
     }
+    if (!empty($item['field']['#default_value'])) {
+      return [$item['field']['#default_value'] => $item['field']['#default_value']];
+    }
     return [];
   }