Code Examples
Illustrative dataset manifests, annotation structures, scenario and evaluation configurations, reports and a dataset lifecycle, in JSON, Python and TypeScript.
Page type: Structured details: fields, formats, statuses.
Dataset manifest
The manifest, a TypeScript type for it, and a validator you can run with any Python 3.9+ installation.
dataset_manifest.jsonIllustrative
JSON
{
"dataset_id": "example-maize-weed-seg",
"dataset_version": "1.0.0",
"created_at": "2026-01-15T09:00:00Z",
"license": "CC-BY-4.0",
"task_type": "semantic-segmentation",
"annotation_format": "png-indexed-masks",
"classes": [
"soil",
"crop",
"weed"
],
"scenario_reference": "scenarios/maize-weed-overcast-v1.json",
"sample_count": 240,
"splits": {
"train": 168,
"validation": 36,
"test": 36
},
"provenance": {
"source": "synthetic",
"generator": "illustrative-example",
"seed": 1234
}
}validate_manifest.pyStandard library only
Python
"""Validate a dataset manifest using only the Python standard library.
This is an educational example, not part of a Synthex package.
Usage: python validate_manifest.py dataset_manifest.json
"""
import json
import re
import sys
from datetime import datetime
REQUIRED = {
"dataset_id": str,
"dataset_version": str,
"created_at": str,
"license": str,
"task_type": str,
"annotation_format": str,
"classes": list,
"sample_count": int,
"splits": dict,
"provenance": dict,
}
def validate(manifest: dict) -> list[str]:
errors = []
for field, expected in REQUIRED.items():
if field not in manifest:
errors.append(f"missing field: {field}")
elif not isinstance(manifest[field], expected):
errors.append(f"{field} should be {expected.__name__}")
if errors:
return errors
if not re.fullmatch(r"\d+\.\d+\.\d+", manifest["dataset_version"]):
errors.append("dataset_version should look like 1.0.0")
try:
datetime.fromisoformat(manifest["created_at"].replace("Z", "+00:00"))
except ValueError:
errors.append("created_at should be an ISO 8601 timestamp")
if len(set(manifest["classes"])) != len(manifest["classes"]):
errors.append("classes contains duplicates")
if sum(manifest["splits"].values()) != manifest["sample_count"]:
errors.append("splits do not add up to sample_count")
return errors
if __name__ == "__main__":
with open(sys.argv[1], encoding="utf-8") as handle:
data = json.load(handle)
problems = validate(data)
for problem in problems:
print(f"ERROR: {problem}")
if problems:
sys.exit(1)
print(f"Manifest OK: {data['dataset_id']} {data['dataset_version']} ({data['sample_count']} samples)")
dataset-manifest.tsIllustrative
TypeScript
// Illustrative TypeScript type for the example dataset manifest.
// Not part of a published Synthex package.
export type DatasetManifest = {
dataset_id: string;
dataset_version: string; // semantic version, e.g. "1.0.0"
created_at: string; // ISO 8601, UTC
license: string; // SPDX identifier
task_type: "image-classification" | "object-detection" | "semantic-segmentation";
annotation_format: string;
classes: string[];
scenario_reference?: string;
sample_count: number;
splits: Record<"train" | "validation" | "test", number>;
provenance: {
source: "real" | "synthetic" | "mixed";
generator: string;
seed?: number;
};
};
export function splitsMatchCount(manifest: DatasetManifest): boolean {
const total = Object.values(manifest.splits).reduce((sum, n) => sum + n, 0);
return total === manifest.sample_count;
}
Run the validator
Shell
python validate_manifest.py dataset_manifest.jsonExample output
Manifest OK: example-maize-weed-seg 1.0.0 (240 samples)
Segmentation annotation structure
A COCO-style record for one weed instance: polygon, bounding box and area.
annotations.jsonIllustrative
JSON
{
"images": [
{
"id": 17,
"file_name": "images/field_000017.png",
"width": 640,
"height": 480
}
],
"categories": [
{
"id": 1,
"name": "crop"
},
{
"id": 2,
"name": "weed"
}
],
"annotations": [
{
"id": 301,
"image_id": 17,
"category_id": 2,
"segmentation": [
[
212,
96,
231.5,
94,
238,
110.5,
220,
118,
209.5,
108
]
],
"bbox": [
209.5,
94,
28.5,
24
],
"area": 471.25,
"iscrowd": 0
}
]
}Scenario configuration
Generated with the same logic as the scenario explorer in the Simulation Engine guide.
scenarios/agricultural-dusk-clear.jsonIllustrative
JSON
{
"scenario_id": "example-agricultural-dusk-clear",
"version": "0.1.0",
"environment": {
"type": "agricultural",
"objects": [
"crop rows",
"weeds",
"soil",
"field machinery"
]
},
"lighting": {
"time_of_day": "dusk"
},
"weather": {
"condition": "clear"
},
"agents": {
"behaviour": "a slow-moving field vehicle"
},
"sensors": [
{
"id": "sensor_0",
"type": "rgb_camera",
"resolution": [
1280,
720
],
"fov_deg": 90,
"frame_rate_hz": 10
}
],
"random_seed": 1234,
"output": {
"frames": 200,
"task": "semantic-segmentation",
"annotations": [
"semantic_mask"
]
}
}Evaluation configuration
experiments/EXP-SAMPLE-014.jsonIllustrative
JSON
{
"experiment_id": "EXP-SAMPLE-014",
"model_reference": {
"name": "example-segmentation-model",
"version": "0.3.0",
"checkpoint_sha256": "<recorded at run time>"
},
"dataset_reference": "example-maize-weed-seg",
"dataset_version": "1.0.0",
"evaluation_protocol": {
"split": "test",
"held_out_real_data": true,
"resize": [
512,
512
],
"threshold": 0.5
},
"metrics": [
"iou",
"dice",
"precision",
"recall"
],
"scenario_groups": [
"clear-day",
"overcast",
"dusk",
"dense-weeds"
],
"random_seed": 1234
}experiment-config.tsIllustrative
TypeScript
// Illustrative TypeScript type for the example experiment configuration.
// Not part of a published Synthex package.
export type ExperimentConfig = {
experiment_id: string;
model_reference: { name: string; version: string; checkpoint_sha256: string };
dataset_reference: string;
dataset_version: string;
evaluation_protocol: {
split: "validation" | "test";
held_out_real_data: boolean;
resize?: [number, number];
threshold?: number;
};
metrics: Array<"accuracy" | "precision" | "recall" | "f1" | "map" | "iou" | "dice">;
scenario_groups: string[];
random_seed: number;
};
Experiment report
A machine-readable report. All values are sample data, flagged by sample_data: true.
evaluation/EXP-SAMPLE-014-report.jsonSample data
JSON
{
"experiment_id": "EXP-SAMPLE-014",
"sample_data": true,
"summary": "Illustrative report layout. Values are sample data, not results.",
"dataset": {
"reference": "example-maize-weed-seg",
"version": "1.0.0",
"split": "test"
},
"model": {
"name": "example-segmentation-model",
"version": "0.3.0"
},
"conditions": [
"clear-day",
"overcast",
"dusk",
"dense-weeds"
],
"metrics": {
"overall": {
"iou": 0.71,
"dice": 0.83
},
"by_condition": {
"clear-day": {
"iou": 0.76,
"dice": 0.86
},
"overcast": {
"iou": 0.72,
"dice": 0.84
},
"dusk": {
"iou": 0.63,
"dice": 0.77
},
"dense-weeds": {
"iou": 0.6,
"dice": 0.75
}
}
},
"failure_categories": [
{
"category": "weed missed under crop canopy",
"count": 14
},
{
"category": "soil texture labelled as weed",
"count": 9
},
{
"category": "boundary error at row edges",
"count": 21
}
],
"limitations": [
"Sample values only.",
"Single seed; no confidence intervals.",
"No real-world field validation."
],
"next_experiments": [
"Add dusk and dense-weed scenarios to the training data.",
"Repeat with three seeds.",
"Validate on held-out real field images."
]
}End-to-end dataset lifecycle
The intended lifecycle in one place, as pseudocode.
lifecycle (pseudocode)Pseudocode
Python
# PSEUDOCODE: illustrative only. These functions are NOT provided by any
# released Synthex package or API; they name the intended lifecycle stages.
requirements = describe_task(task="semantic-segmentation", classes=["soil", "crop", "weed"])
scenario = configure_scenario(environment="agricultural", lighting="overcast", seed=1234)
samples = generate_or_acquire(scenario, frames=240)
annotations = prepare_annotations(samples, format="png-indexed-masks")
report = run_quality_checks(samples, annotations) # missing files, invalid classes, duplicates
if report.passed:
manifest = package_dataset(samples, annotations, version="1.0.0", license="CC-BY-4.0")
# Training happens in your own environment, with your own framework.
results = evaluate(model_reference, manifest, protocol="held-out-real-test")
next_scenarios = refine_scenarios(results.failure_categories)
Each stage is explained in the engine guides: