feat(formats): add CbeffSerializer — CBEFF-like JSON envelope format

Wraps any generated record in a CBEFF-inspired JSON envelope with
cbeff_version, format_owner, format_type, creation_date, and payload
fields. subject_id is promoted to the envelope level when present in
the record.

- CbeffSerializer: stateless, thread-safe, configurable owner/type
- CLI: --format cbeff wired; reads cbeff_format_owner / cbeff_format_type
  from job conf if present, falls back to ISO/IEC-JTC1-SC37 defaults
- 10 unit tests (CbeffSerializerTest), all passing
- Directly enables biometric pipeline testing against the fingerprint
  and face YAML structures added in the previous commit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mferretti

cli/src/main/java/com/datagenerator/cli/ExecuteCommand.java

@@ -33,6 +33,7 @@
 import com.datagenerator.destinations.kafka.KafkaDestination;
 import com.datagenerator.destinations.kafka.KafkaDestinationConfig;
 import com.datagenerator.formats.FormatSerializer;
+import com.datagenerator.formats.cbeff.CbeffSerializer;
 import com.datagenerator.formats.csv.CsvSerializer;
 import com.datagenerator.formats.json.JsonSerializer;
 import com.datagenerator.formats.protobuf.ProtobufSerializer;
@@ -406,7 +407,7 @@ public Integer call() throws Exception {
         dataStructure.getData().size());
 
     // 4. Create format serializer
-    FormatSerializer serializer = createSerializer(format);
+    FormatSerializer serializer = createSerializer(format, jobConfig);
     log.info("Created serializer: {}", serializer.getFormatName());
 
     // 5. Create destination adapter
@@ -509,15 +510,28 @@ private long resolveSeed(JobConfig jobConfig) {
   /**
    * Creates a format serializer based on the specified format string.
    *
-   * @param format format name ("json" or "csv", case-insensitive)
+   * @param format format name ("json", "csv", "protobuf", "cbeff", case-insensitive)
+   * @param jobConfig job configuration (used for cbeff-specific conf values)
    * @return serializer instance for the specified format
    * @throws IllegalArgumentException if format is unsupported
    */
-  private FormatSerializer createSerializer(String format) {
+  private FormatSerializer createSerializer(String format, JobConfig jobConfig) {
     return switch (format.toLowerCase(Locale.ROOT)) {
       case "json" -> new JsonSerializer();
       case "csv" -> new CsvSerializer();
       case "protobuf" -> new ProtobufSerializer();
+      case "cbeff" -> {
+        JsonNode conf = jobConfig.getConf();
+        String owner =
+            conf != null && conf.has("cbeff_format_owner")
+                ? conf.get("cbeff_format_owner").asText()
+                : CbeffSerializer.DEFAULT_FORMAT_OWNER;
+        String type =
+            conf != null && conf.has("cbeff_format_type")
+                ? conf.get("cbeff_format_type").asText()
+                : CbeffSerializer.DEFAULT_FORMAT_TYPE;
+        yield new CbeffSerializer(owner, type);
+      }
       default -> throw new IllegalArgumentException("Unsupported format: " + format);
     };
   }

docs/internal/tasks/README.md

@@ -98,9 +98,12 @@ Each task lists dependencies on other tasks. Always complete dependencies before
 - [TASK-036: Security - File Permission Checks](TASK-036-security-permissions.md) ⏸️
 - [TASK-044: Extras Directory — External JARs and Custom Datafaker Providers](TASK-044-extras-directory-plugin-loading.md) ✅
 
-### Phase 10: Future Enhancements (⏸️ Not Started)
+### Phase 10: Future Enhancements (🔄 In Progress)
 - [TASK-037: API - REST Interface](TASK-037-api-rest.md) ⏸️ (future enhancement)
 - [TASK-038: API - gRPC Interface](TASK-038-api-grpc.md) ⏸️ (future enhancement)
+- [TASK-047: Biometric YAML Structure Definitions](TASK-047-biometric-yaml-structures.md) ✅
+- [TASK-048: CBEFF JSON Wrapper Serializer](TASK-048-cbeff-json-serializer.md) ✅
+- [TASK-049: BiometricValidator and validate CLI command](TASK-049-biometric-validator.md) ⏸️
 
 ---
 

docs/internal/tasks/TASK-048-cbeff-json-serializer.md

@@ -1,6 +1,7 @@
 # TASK-048: CBEFF JSON Wrapper Serializer
 
-**Status:** Deferred ⏸️ (Future Enhancement)
+**Status:** ✅ Complete
+**Completion Date:** March 15, 2026
 **Priority:** P3
 **Phase:** Phase 10 (Biometric Data Generation)
 **Effort:** 3–4h

formats/src/main/java/com/datagenerator/formats/cbeff/CbeffSerializer.java

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2026 Marco Ferretti
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.datagenerator.formats.cbeff;
+
+import com.datagenerator.formats.FormatSerializer;
+import com.datagenerator.formats.SerializationException;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import java.time.Instant;
+import java.time.format.DateTimeFormatter;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Serializes generated records to a CBEFF-like JSON envelope format.
+ *
+ * <p>Wraps any generated record in a Common Biometric Exchange Formats Framework (CBEFF) inspired
+ * JSON envelope, enabling testing of biometric exchange pipelines that expect a {@code
+ * format_owner} / {@code format_type} metadata wrapper around the payload.
+ *
+ * <p><b>Envelope structure:</b>
+ *
+ * <pre>{@code
+ * {
+ *   "cbeff_version": "1.1",
+ *   "format_owner": "ISO/IEC-JTC1-SC37",
+ *   "format_type": "biometric-json",
+ *   "creation_date": "2026-03-15T10:00:00Z",
+ *   "subject_id": "<promoted from payload if present>",
+ *   "payload": { ...original record... }
+ * }
+ * }</pre>
+ *
+ * <p><b>Thread Safety:</b> Stateless — {@code Instant.now()} is called per record. ObjectMapper is
+ * thread-safe after configuration.
+ */
+@Slf4j
+public class CbeffSerializer implements FormatSerializer {
+
+  public static final String CBEFF_VERSION = "1.1";
+  public static final String DEFAULT_FORMAT_OWNER = "ISO/IEC-JTC1-SC37";
+  public static final String DEFAULT_FORMAT_TYPE = "biometric-json";
+
+  private final String formatOwner;
+  private final String formatType;
+  private final ObjectMapper mapper;
+
+  /** Create CBEFF serializer with default format owner and type. */
+  public CbeffSerializer() {
+    this(DEFAULT_FORMAT_OWNER, DEFAULT_FORMAT_TYPE);
+  }
+
+  /**
+   * Create CBEFF serializer with configurable format owner and type.
+   *
+   * @param formatOwner CBEFF format owner identifier (e.g. "ISO/IEC-JTC1-SC37")
+   * @param formatType CBEFF format type identifier (e.g. "19794-2-json")
+   */
+  public CbeffSerializer(String formatOwner, String formatType) {
+    this.formatOwner = formatOwner;
+    this.formatType = formatType;
+    this.mapper = createObjectMapper();
+  }
+
+  private static ObjectMapper createObjectMapper() {
+    ObjectMapper m = new ObjectMapper();
+    m.registerModule(new JavaTimeModule());
+    m.disable(SerializationFeature.INDENT_OUTPUT);
+    m.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+    return m;
+  }
+
+  @Override
+  public String serialize(Map<String, Object> record) {
+    Map<String, Object> envelope = new LinkedHashMap<>();
+    envelope.put("cbeff_version", CBEFF_VERSION);
+    envelope.put("format_owner", formatOwner);
+    envelope.put("format_type", formatType);
+    envelope.put("creation_date", DateTimeFormatter.ISO_INSTANT.format(Instant.now()));
+
+    Object subjectId = record.get("subject_id");
+    if (subjectId != null) {
+      envelope.put("subject_id", subjectId);
+    }
+
+    envelope.put("payload", record);
+
+    try {
+      return mapper.writeValueAsString(envelope);
+    } catch (JsonProcessingException e) {
+      log.error("Failed to serialize record to CBEFF JSON: {}", record, e);
+      throw new SerializationException("CBEFF serialization failed", e);
+    }
+  }
+
+  @Override
+  public String getFormatName() {
+    return "cbeff";
+  }
+}

formats/src/main/java/com/datagenerator/formats/cbeff/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2026 Marco Ferretti
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * CBEFF-like JSON envelope serialization for biometric records.
+ *
+ * <p>Wraps generated records in a Common Biometric Exchange Formats Framework inspired JSON
+ * envelope with configurable {@code format_owner} and {@code format_type} metadata.
+ */
+package com.datagenerator.formats.cbeff;

formats/src/test/java/com/datagenerator/formats/cbeff/CbeffSerializerTest.java

@@ -0,0 +1,137 @@
+/*
+ * Copyright 2026 Marco Ferretti
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.datagenerator.formats.cbeff;
+
+import static org.assertj.core.api.Assertions.*;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+class CbeffSerializerTest {
+
+  private CbeffSerializer serializer;
+  private ObjectMapper mapper;
+
+  @BeforeEach
+  void setUp() {
+    serializer = new CbeffSerializer();
+    mapper = new ObjectMapper();
+  }
+
+  @Test
+  void shouldReturnFormatName() {
+    assertThat(serializer.getFormatName()).isEqualTo("cbeff");
+  }
+
+  @Test
+  void shouldIncludeRequiredEnvelopeFields() throws Exception {
+    Map<String, Object> record = Map.of("name", "Alice");
+    JsonNode envelope = mapper.readTree(serializer.serialize(record));
+
+    assertThat(envelope.has("cbeff_version")).isTrue();
+    assertThat(envelope.has("format_owner")).isTrue();
+    assertThat(envelope.has("format_type")).isTrue();
+    assertThat(envelope.has("creation_date")).isTrue();
+    assertThat(envelope.has("payload")).isTrue();
+  }
+
+  @Test
+  void shouldUseDefaultFormatOwnerAndType() throws Exception {
+    Map<String, Object> record = Map.of("field", "value");
+    JsonNode envelope = mapper.readTree(serializer.serialize(record));
+
+    assertThat(envelope.get("format_owner").asText())
+        .isEqualTo(CbeffSerializer.DEFAULT_FORMAT_OWNER);
+    assertThat(envelope.get("format_type").asText()).isEqualTo(CbeffSerializer.DEFAULT_FORMAT_TYPE);
+    assertThat(envelope.get("cbeff_version").asText()).isEqualTo(CbeffSerializer.CBEFF_VERSION);
+  }
+
+  @Test
+  void shouldApplyCustomFormatOwnerAndType() throws Exception {
+    CbeffSerializer custom = new CbeffSerializer("ACME-Corp", "19794-2-json");
+    Map<String, Object> record = Map.of("field", "value");
+    JsonNode envelope = mapper.readTree(custom.serialize(record));
+
+    assertThat(envelope.get("format_owner").asText()).isEqualTo("ACME-Corp");
+    assertThat(envelope.get("format_type").asText()).isEqualTo("19794-2-json");
+  }
+
+  @Test
+  void shouldContainOriginalRecordUnderPayload() throws Exception {
+    Map<String, Object> record = Map.of("finger_position", "right_index", "quality", 85);
+    JsonNode envelope = mapper.readTree(serializer.serialize(record));
+
+    JsonNode payload = envelope.get("payload");
+    assertThat(payload.get("finger_position").asText()).isEqualTo("right_index");
+    assertThat(payload.get("quality").asInt()).isEqualTo(85);
+  }
+
+  @Test
+  void shouldPromoteSubjectIdToEnvelope() throws Exception {
+    Map<String, Object> record = new LinkedHashMap<>();
+    record.put("subject_id", "SUBJ-001");
+    record.put("quality", 90);
+    JsonNode envelope = mapper.readTree(serializer.serialize(record));
+
+    assertThat(envelope.get("subject_id").asText()).isEqualTo("SUBJ-001");
+    // subject_id also remains in payload
+    assertThat(envelope.get("payload").get("subject_id").asText()).isEqualTo("SUBJ-001");
+  }
+
+  @Test
+  void shouldNotIncludeSubjectIdInEnvelopeWhenAbsentFromRecord() throws Exception {
+    Map<String, Object> record = Map.of("name", "Alice");
+    JsonNode envelope = mapper.readTree(serializer.serialize(record));
+
+    assertThat(envelope.has("subject_id")).isFalse();
+  }
+
+  @Test
+  void shouldProduceValidJsonForEmptyRecord() throws Exception {
+    Map<String, Object> record = Map.of();
+    String output = serializer.serialize(record);
+
+    JsonNode envelope = mapper.readTree(output);
+    assertThat(envelope.get("payload").isEmpty()).isTrue();
+  }
+
+  @Test
+  void shouldIncludeValidIso8601CreationDate() throws Exception {
+    Map<String, Object> record = Map.of("field", "value");
+    JsonNode envelope = mapper.readTree(serializer.serialize(record));
+
+    String creationDate = envelope.get("creation_date").asText();
+    // ISO-8601 instant ends with Z
+    assertThat(creationDate).endsWith("Z");
+    assertThat(creationDate).matches("\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z");
+  }
+
+  @Test
+  void shouldProduceValidJsonRoundTrip() throws Exception {
+    Map<String, Object> record = Map.of("x", 100, "y", 200, "type", "ending");
+    String output = serializer.serialize(record);
+
+    // Must parse without error
+    JsonNode envelope = mapper.readTree(output);
+    assertThat(envelope.isObject()).isTrue();
+    assertThat(envelope.get("payload").get("x").asInt()).isEqualTo(100);
+  }
+}