Add ObjectListField support with validation and JSON Schema export

Author: Juan Pablo Manson

README.md

@@ -87,6 +87,69 @@ All fields inherit from `FormFieldBase` and share these common attributes:
   - `accept`: Accepted file types (e.g. `"image/*,.pdf"`).
   - `multiple`: Allow multiple file uploads.
 - **`HiddenField`** — Hidden field (`<input type="hidden">`).
+- **`ListField`** — Array of primitive values.
+  - `item_type`: Primitive type for each item (`text`, `number`, `email`, `url`, `date`).
+  - `min_items`, `max_items`: List size limits.
+- **`ObjectListField`** — Array of homogeneous objects validated against nested subfields.
+  - `fields`: List of subfields that define each object shape.
+  - `min_items`, `max_items`: List size limits.
+
+### `ObjectListField`
+
+Use `ObjectListField` when a form needs a repeatable list of structured rows, such as parallel approvers, attendees with roles, or line items.
+
+```python
+from codeforms import Form, ObjectListField, TextField, CheckboxField
+
+form = Form(
+    name="parallel_approvers",
+    fields=[
+        ObjectListField(
+            name="parallel_approvals",
+            label="Aprobadores",
+            required=True,
+            min_items=1,
+            max_items=5,
+            fields=[
+                TextField(name="approver_email", label="Email", required=True),
+                TextField(name="label", label="Etiqueta", required=True),
+                CheckboxField(name="required", label="Obligatorio"),
+            ],
+        )
+    ],
+)
+```
+
+Expected submitted value:
+
+```json
+{
+  "parallel_approvals": [
+    {
+      "approver_email": "ana@empresa.com",
+      "label": "Compras",
+      "required": true
+    },
+    {
+      "approver_email": "luis@empresa.com",
+      "label": "Finanzas"
+    }
+  ]
+}
+```
+
+Validation behavior:
+
+- The top-level field must be a JSON array.
+- Each item must be a JSON object.
+- Unknown keys inside items are rejected.
+- Required nested subfields are enforced.
+- Validation errors include nested paths like `parallel_approvals[0].label`.
+
+Current limitation:
+
+- `ObjectListField` is fully supported in backend validation and JSON Schema export.
+- Rich repeatable HTML UI generation is not implemented yet. If you need an interactive editor, prefer consuming the exported `json_schema` from your frontend.
 
 ## Data Validation
 
@@ -271,9 +334,38 @@ Output:
 | `UrlField` | `string` (`format: "uri"`) | `minLength`, `maxLength` |
 | `TextareaField` | `string` | `minLength`, `maxLength` |
 | `ListField` | `array` | `minItems`, `maxItems` |
+| `ObjectListField` | `array` of `object` | nested `properties`, nested `required`, `minItems`, `maxItems` |
 
 Field annotations like `label`, `help_text`, `default_value`, and `readonly` map to the JSON Schema keywords `title`, `description`, `default`, and `readOnly` respectively.
 
+Example `ObjectListField` schema:
+
+```json
+{
+  "type": "array",
+  "minItems": 1,
+  "items": {
+    "type": "object",
+    "properties": {
+      "approver_email": {
+        "type": "string",
+        "title": "Email"
+      },
+      "label": {
+        "type": "string",
+        "title": "Etiqueta"
+      },
+      "required": {
+        "type": "boolean",
+        "title": "Obligatorio"
+      }
+    },
+    "required": ["approver_email", "label"],
+    "additionalProperties": false
+  }
+}
+```
+
 Fields inside `FieldGroup` and `FormStep` containers are flattened into the top-level `properties` automatically.
 
 ## Internationalization (i18n)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codeforms"
-version = "0.2.1"
+version = "0.2.2"
 description = "Python library for creating, validating, and rendering web forms using Pydantic"
 readme = "README.md"
 requires-python = ">=3.9"

src/codeforms/__init__.py

@@ -12,6 +12,7 @@
     FormStep,
     HiddenField,
     ListField,
+    ObjectListField,
     NumberField,
     RadioField,
     SelectField,
@@ -63,6 +64,7 @@
     "UrlField",
     "TextareaField",
     "ListField",
+    "ObjectListField",
     "FieldGroup",
     "FormStep",
     # Form

src/codeforms/export.py

@@ -12,6 +12,7 @@
     FormStep,
     HiddenField,
     ListField,
+    ObjectListField,
     NumberField,
     RadioField,
     SelectField,
@@ -485,6 +486,26 @@ def exporter(form: Form, output_format: str, **kwargs) -> dict:
 }
 
 
+def _object_list_item_schema(field: ObjectListField) -> Dict[str, Any]:
+    properties: Dict[str, Any] = {}
+    required = []
+
+    for subfield in field.fields:
+        properties[subfield.name] = _field_to_json_schema_property(subfield)
+        if subfield.required:
+            required.append(subfield.name)
+
+    item_schema: Dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        item_schema["required"] = required
+
+    return item_schema
+
+
 def _field_to_json_schema_property(field: FormFieldBase) -> Dict[str, Any]:
     """Convert a single form field to a JSON Schema property definition."""
     prop: Dict[str, Any] = {}
@@ -570,6 +591,14 @@ def _field_to_json_schema_property(field: FormFieldBase) -> Dict[str, Any]:
         if field.max_items is not None:
             prop["maxItems"] = field.max_items
 
+    elif isinstance(field, ObjectListField):
+        prop["type"] = "array"
+        prop["items"] = _object_list_item_schema(field)
+        if field.min_items is not None:
+            prop["minItems"] = field.min_items
+        if field.max_items is not None:
+            prop["maxItems"] = field.max_items
+
     elif isinstance(field, TextField):
         prop["type"] = "string"
         if field.minlength is not None:

src/codeforms/fields.py

@@ -30,6 +30,7 @@ class FieldType(str, Enum):
     HIDDEN = "hidden"
     URL = "url"
     LIST = "list"
+    OBJECT_LIST = "object-list"
 
 
 class ValidationRule(BaseModel):
@@ -279,14 +280,40 @@ class TextareaField(FormFieldBase):
 
 
 class ListField(FormFieldBase):
-    """Campo para listas de valores (ej: lista de participantes)"""
+    """Campo para listas de valores primitivos (ej: lista de participantes)."""
 
     field_type: FieldType = FieldType.LIST
     min_items: Optional[int] = None
     max_items: Optional[int] = None
     item_type: str = "text"  # Tipo de cada item en la lista
 
 
+class ObjectListField(FormFieldBase):
+    """Campo para listas de objetos homogéneos validados por subcampos."""
+
+    field_type: FieldType = FieldType.OBJECT_LIST
+    min_items: Optional[int] = None
+    max_items: Optional[int] = None
+    fields: List[Any] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def resolve_object_fields(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "fields" in data:
+            from codeforms.registry import resolve_content_item
+
+            data = data.copy()
+            data["fields"] = [resolve_content_item(item) for item in data["fields"]]
+        return data
+
+    @model_validator(mode="after")
+    def validate_object_fields(self) -> "ObjectListField":
+        names = [field.name for field in self.fields]
+        if len(names) != len(set(names)):
+            raise ValueError(t("form.unique_field_names_in_group", title=self.label or self.name))
+        return self
+
+
 class FieldGroup(BaseModel):
     """Representa un grupo de campos en un formulario para organización en secciones"""