Various review updates

- Add specific errors for JSON blob decode

- Update changelog and API docs

- Switch to char* for blobs for consistency

- Update Python changelog

Fixup lint

Author: jeromekelleher

c/CHANGELOG.rst

@@ -4,6 +4,9 @@
 
 In development
 
+- Add ``tsk_json_struct_metadata_get_blob`` function
+  (:user:`benjeffery`, :pr:`3306`)
+
 --------------------
 [1.3.1] - 2026-03-06
 --------------------

c/tests/test_core.c

@@ -86,14 +86,14 @@ test_generate_uuid(void)
 static void
 set_u64_le(uint8_t *dest, uint64_t value)
 {
-    dest[0] = (uint8_t)(value & 0xFF);
-    dest[1] = (uint8_t)((value >> 8) & 0xFF);
-    dest[2] = (uint8_t)((value >> 16) & 0xFF);
-    dest[3] = (uint8_t)((value >> 24) & 0xFF);
-    dest[4] = (uint8_t)((value >> 32) & 0xFF);
-    dest[5] = (uint8_t)((value >> 40) & 0xFF);
-    dest[6] = (uint8_t)((value >> 48) & 0xFF);
-    dest[7] = (uint8_t)((value >> 56) & 0xFF);
+    dest[0] = (uint8_t) (value & 0xFF);
+    dest[1] = (uint8_t) ((value >> 8) & 0xFF);
+    dest[2] = (uint8_t) ((value >> 16) & 0xFF);
+    dest[3] = (uint8_t) ((value >> 24) & 0xFF);
+    dest[4] = (uint8_t) ((value >> 32) & 0xFF);
+    dest[5] = (uint8_t) ((value >> 40) & 0xFF);
+    dest[6] = (uint8_t) ((value >> 48) & 0xFF);
+    dest[7] = (uint8_t) ((value >> 56) & 0xFF);
 }
 
 static void
@@ -103,7 +103,7 @@ test_json_struct_metadata_get_blob(void)
     char metadata[128];
     const char *json;
     tsk_size_t json_buffer_length;
-    const uint8_t *blob;
+    const char *blob;
     tsk_size_t blob_length;
     uint8_t *bytes;
     tsk_size_t metadata_length;
@@ -181,25 +181,25 @@ test_json_struct_metadata_get_blob(void)
     metadata_length = header_length - 1;
     ret = tsk_json_struct_metadata_get_blob(
         metadata, metadata_length, &json, &json_buffer_length, &blob, &blob_length);
-    CU_ASSERT_EQUAL(ret, TSK_ERR_FILE_FORMAT);
+    CU_ASSERT_EQUAL(ret, TSK_ERR_JSON_STRUCT_METADATA_TRUNCATED);
 
     metadata_length = (tsk_size_t) total_length;
     bytes[0] = 'X';
     ret = tsk_json_struct_metadata_get_blob(
         metadata, metadata_length, &json, &json_buffer_length, &blob, &blob_length);
-    CU_ASSERT_EQUAL(ret, TSK_ERR_FILE_FORMAT);
+    CU_ASSERT_EQUAL(ret, TSK_ERR_JSON_STRUCT_METADATA_BAD_MAGIC);
     bytes[0] = 'J';
 
     bytes[4] = 2;
     ret = tsk_json_struct_metadata_get_blob(
         metadata, metadata_length, &json, &json_buffer_length, &blob, &blob_length);
-    CU_ASSERT_EQUAL(ret, TSK_ERR_FILE_VERSION_TOO_NEW);
+    CU_ASSERT_EQUAL(ret, TSK_ERR_JSON_STRUCT_METADATA_BAD_VERSION);
     bytes[4] = 1;
 
-    metadata_length = (tsk_size_t)(total_length - 1);
+    metadata_length = (tsk_size_t) (total_length - 1);
     ret = tsk_json_struct_metadata_get_blob(
         metadata, metadata_length, &json, &json_buffer_length, &blob, &blob_length);
-    CU_ASSERT_EQUAL(ret, TSK_ERR_FILE_FORMAT);
+    CU_ASSERT_EQUAL(ret, TSK_ERR_JSON_STRUCT_METADATA_TRUNCATED);
 
     ret = tsk_json_struct_metadata_get_blob(
         NULL, metadata_length, &json, &json_buffer_length, &blob, &blob_length);
@@ -229,13 +229,13 @@ test_json_struct_metadata_get_blob(void)
     set_u64_le(bytes + 13, 0);
     ret = tsk_json_struct_metadata_get_blob(
         metadata, metadata_length, &json, &json_buffer_length, &blob, &blob_length);
-    CU_ASSERT_EQUAL(ret, TSK_ERR_FILE_FORMAT);
+    CU_ASSERT_EQUAL(ret, TSK_ERR_JSON_STRUCT_METADATA_INVALID_LENGTH);
 
     set_u64_le(bytes + 5, 8);
-    set_u64_le(bytes + 13, UINT64_MAX - (uint64_t)(header_length + 8) + 1);
+    set_u64_le(bytes + 13, UINT64_MAX - (uint64_t) (header_length + 8) + 1);
     ret = tsk_json_struct_metadata_get_blob(
         metadata, metadata_length, &json, &json_buffer_length, &blob, &blob_length);
-    CU_ASSERT_EQUAL(ret, TSK_ERR_FILE_FORMAT);
+    CU_ASSERT_EQUAL(ret, TSK_ERR_JSON_STRUCT_METADATA_INVALID_LENGTH);
 }
 
 static void

c/tskit/core.c

@@ -32,10 +32,10 @@
 #include <kastore.h>
 #include <tskit/core.h>
 
-#define UUID_NUM_BYTES 16
+#define UUID_NUM_BYTES              16
 #define TSK_JSON_BINARY_HEADER_SIZE 21
 
-static const uint8_t TSK_JSON_BINARY_MAGIC[4] = { 'J', 'B', 'L', 'B' };
+static const uint8_t _tsk_json_binary_magic[4] = { 'J', 'B', 'L', 'B' };
 
 #if defined(_WIN32)
 
@@ -143,7 +143,7 @@ tsk_generate_uuid(char *dest, int TSK_UNUSED(flags))
 
 int
 tsk_json_struct_metadata_get_blob(const char *metadata, tsk_size_t metadata_length,
-    const char **json, tsk_size_t *json_length, const uint8_t **blob,
+    const char **json, tsk_size_t *json_length, const char **blob,
     tsk_size_t *blob_length)
 {
     int ret;
@@ -153,7 +153,7 @@ tsk_json_struct_metadata_get_blob(const char *metadata, tsk_size_t metadata_leng
     uint64_t header_and_json_length;
     uint64_t total_length;
     const uint8_t *bytes;
-    const uint8_t *blob_start;
+    const char *blob_start;
     const char *json_start;
 
     if (metadata == NULL || json == NULL || json_length == NULL || blob == NULL
@@ -163,36 +163,36 @@ tsk_json_struct_metadata_get_blob(const char *metadata, tsk_size_t metadata_leng
     }
     bytes = (const uint8_t *) metadata;
     if (metadata_length < TSK_JSON_BINARY_HEADER_SIZE) {
-        ret = tsk_trace_error(TSK_ERR_FILE_FORMAT);
+        ret = tsk_trace_error(TSK_ERR_JSON_STRUCT_METADATA_TRUNCATED);
         goto out;
     }
-    if (memcmp(bytes, TSK_JSON_BINARY_MAGIC, sizeof(TSK_JSON_BINARY_MAGIC)) != 0) {
-        ret = tsk_trace_error(TSK_ERR_FILE_FORMAT);
+    if (memcmp(bytes, _tsk_json_binary_magic, sizeof(_tsk_json_binary_magic)) != 0) {
+        ret = tsk_trace_error(TSK_ERR_JSON_STRUCT_METADATA_BAD_MAGIC);
         goto out;
     }
     version = bytes[4];
     if (version != 1) {
-        ret = tsk_trace_error(TSK_ERR_FILE_VERSION_TOO_NEW);
+        ret = tsk_trace_error(TSK_ERR_JSON_STRUCT_METADATA_BAD_VERSION);
         goto out;
     }
     json_length_u64 = tsk_load_u64_le(bytes + 5);
     binary_length_u64 = tsk_load_u64_le(bytes + 13);
     if (json_length_u64 > UINT64_MAX - (uint64_t) TSK_JSON_BINARY_HEADER_SIZE) {
-        ret = tsk_trace_error(TSK_ERR_FILE_FORMAT);
+        ret = tsk_trace_error(TSK_ERR_JSON_STRUCT_METADATA_INVALID_LENGTH);
         goto out;
     }
     header_and_json_length = (uint64_t) TSK_JSON_BINARY_HEADER_SIZE + json_length_u64;
     if (binary_length_u64 > UINT64_MAX - header_and_json_length) {
-        ret = tsk_trace_error(TSK_ERR_FILE_FORMAT);
+        ret = tsk_trace_error(TSK_ERR_JSON_STRUCT_METADATA_INVALID_LENGTH);
         goto out;
     }
     total_length = header_and_json_length + binary_length_u64;
     if ((uint64_t) metadata_length < total_length) {
-        ret = tsk_trace_error(TSK_ERR_FILE_FORMAT);
+        ret = tsk_trace_error(TSK_ERR_JSON_STRUCT_METADATA_TRUNCATED);
         goto out;
     }
     json_start = (const char *) bytes + TSK_JSON_BINARY_HEADER_SIZE;
-    blob_start = bytes + TSK_JSON_BINARY_HEADER_SIZE + json_length_u64;
+    blob_start = (const char *) bytes + TSK_JSON_BINARY_HEADER_SIZE + json_length_u64;
     *json = json_start;
     *json_length = (tsk_size_t) json_length_u64;
     *blob = blob_start;
@@ -268,6 +268,22 @@ tsk_strerror_internal(int err)
             ret = "An incompatible type for a column was found in the file. "
                   "(TSK_ERR_BAD_COLUMN_TYPE)";
             break;
+        case TSK_ERR_JSON_STRUCT_METADATA_BAD_MAGIC:
+            ret = "JSON binary struct metadata does not begin with the expected "
+                  "magic bytes. (TSK_ERR_JSON_STRUCT_METADATA_BAD_MAGIC)";
+            break;
+        case TSK_ERR_JSON_STRUCT_METADATA_TRUNCATED:
+            ret = "JSON binary struct metadata is shorter than the expected size. "
+                  "(TSK_ERR_JSON_STRUCT_METADATA_TRUNCATED)";
+            break;
+        case TSK_ERR_JSON_STRUCT_METADATA_INVALID_LENGTH:
+            ret = "A length field in the JSON binary struct metadata header is invalid. "
+                  "(TSK_ERR_JSON_STRUCT_METADATA_INVALID_LENGTH)";
+            break;
+        case TSK_ERR_JSON_STRUCT_METADATA_BAD_VERSION:
+            ret = "JSON binary struct metadata uses an unsupported version number. "
+                  "(TSK_ERR_JSON_STRUCT_METADATA_BAD_VERSION)";
+            break;
 
         /* Out of bounds errors */
         case TSK_ERR_BAD_OFFSET:

c/tskit/core.h

@@ -309,6 +309,26 @@ not found in the file.
 An unsupported type was provided for a column in the file.
 */
 #define TSK_ERR_BAD_COLUMN_TYPE                                     -105
+
+/**
+The JSON binary struct metadata does not begin with the expected magic bytes.
+*/
+#define TSK_ERR_JSON_STRUCT_METADATA_BAD_MAGIC                      -106
+
+/**
+The JSON binary struct metadata is shorter than the expected size.
+*/
+#define TSK_ERR_JSON_STRUCT_METADATA_TRUNCATED                      -107
+
+/**
+A length field in the JSON binary struct metadata header is invalid.
+*/
+#define TSK_ERR_JSON_STRUCT_METADATA_INVALID_LENGTH                 -108
+
+/**
+The JSON binary struct metadata uses an unsupported version number.
+*/
+#define TSK_ERR_JSON_STRUCT_METADATA_BAD_VERSION                    -109
 /** @} */
 
 /**
@@ -1116,7 +1136,7 @@ int tsk_generate_uuid(char *dest, int flags);
 @brief Extract the binary payload from ``json+struct`` encoded metadata.
 
 @rst
-Metadata produced by :py:class:`tskit.metadata.JSONStructCodec` consists of a fixed-size
+Metadata produced by the JSONStructCodec consists of a fixed-size
 header followed by canonical JSON bytes and an optional binary payload. This helper
 validates the framing, returning pointers to the embedded JSON and binary sections
 without copying.
@@ -1131,10 +1151,10 @@ the original metadata buffer is alive.
 @param[out] json_length On success, set to the JSON length in bytes.
 @param[out] blob On success, set to the start of the binary payload.
 @param[out] blob_length On success, set to the payload length in bytes.
-@return 0 on success, or a :ref:`TSK_ERR <c_api_errors>` code on failure.
+@return Return 0 on success or a negative value on failure.
 */
 int tsk_json_struct_metadata_get_blob(const char *metadata, tsk_size_t metadata_length,
-    const char **json, tsk_size_t *json_length, const uint8_t **blob,
+    const char **json, tsk_size_t *json_length, const char **blob,
     tsk_size_t *blob_length);
 
 /* TODO most of these can probably be macros so they compile out as no-ops.

docs/c-api.rst

@@ -620,6 +620,7 @@ Miscellaneous functions
 
 .. doxygenfunction:: tsk_is_unknown_time
 
+.. doxygenfunction:: tsk_json_struct_metadata_get_blob
 
 *************************
 Function Specific Options

python/CHANGELOG.rst

@@ -4,6 +4,9 @@
 
 In development
 
+- Add ``json+struct`` metadata codec that allows storing binary data using a struct
+  schema alongside JSON metadata. (:user:`benjeffery`, :pr:`3306`)
+
 --------------------
 [1.0.2] - 2026-03-06
 --------------------
@@ -107,8 +110,6 @@ Maintenance release.
   also around 10% faster.
   (:user:`benjeffery`, :pr:`3313`, :pr:`3317`, :issue:`1896`)
 
-- Add ``json+struct`` metadata codec that allows storing binary data using a struct
-  schema alongside JSON metadata. (:user:`benjeffery`, :pr:`3306`)
 
 **Bugfixes**
 

python/tskit/metadata.py

@@ -208,7 +208,7 @@ class JSONStructCodec(AbstractMetadataCodec):
     _HDR = struct.Struct("<4sBQQ")  # magic, version, json_len, blob_len
 
     @classmethod
-    def is_schema_trivial(self, schema: Mapping) -> bool:
+    def is_schema_trivial(cls, schema: Mapping) -> bool:
         return False
 
     def __init__(self, schema: Mapping[str, Any]) -> None:
@@ -265,9 +265,7 @@ def __init__(self, schema: Mapping[str, Any]) -> None:
         self.struct_codec = StructCodec(self.struct_schema)
         self._struct_keys = set(struct_props.keys())
         self._validate_json = TSKITMetadataSchemaValidator(self.json_schema).validate
-        self._validate_struct = TSKITMetadataSchemaValidator(
-            self.struct_schema
-        ).validate
+        self._validate_struct = TSKITMetadataSchemaValidator(self.struct_schema).validate
 
     def validate_row(self, row: Any) -> None:
         if not isinstance(row, dict):