Let a project record its own attributes on stations and device types

ami/main/api/serializers.py

@@ -535,6 +535,7 @@ class Meta(DeploymentListSerializer.Meta):
             "data_source_subdir",
             "data_source_regex",
             "description",
+            "metadata",
             "example_captures",
             "manually_uploaded_captures",
             # "capture_images",
@@ -1787,6 +1788,7 @@ class Meta:
             "details",
             "name",
             "description",
+            "metadata",
             "project",
             "created_at",
             "updated_at",

ami/main/migrations/0096_deployment_metadata_device_metadata.py

@@ -0,0 +1,33 @@
+# Generated by Django 4.2.10 on 2026-09-07 19:31
+
+import ami.main.models
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("main", "0095_grant_sync_deployment_to_mldatamanager"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="deployment",
+            name="metadata",
+            field=models.JSONField(
+                blank=True,
+                default=dict,
+                help_text="Free-form JSON object holding attributes specific to this configuration, beyond the fields modelled natively. Camera height or habitat description, for example.",
+                validators=[ami.main.models.validate_metadata_object],
+            ),
+        ),
+        migrations.AddField(
+            model_name="device",
+            name="metadata",
+            field=models.JSONField(
+                blank=True,
+                default=dict,
+                help_text="Free-form JSON object holding attributes specific to this configuration, beyond the fields modelled natively. Camera height or habitat description, for example.",
+                validators=[ami.main.models.validate_metadata_object],
+            ),
+        ),
+    ]

ami/main/models.py

@@ -632,6 +632,54 @@ class Meta:
         unique_together = ("user", "project")
 
 
+# JSON type names used when telling an API client what shape it sent instead of an object.
+_JSON_TYPE_NAMES: Final = {
+    bool: "a boolean",
+    dict: "an object",
+    float: "a number",
+    int: "a number",
+    list: "an array",
+    str: "a string",
+    type(None): "null",
+}
+
+
+def validate_metadata_object(value: typing.Any) -> None:
+    """
+    Require metadata to be a JSON object, so its keys stay queryable and mappable.
+
+    The contents are deliberately unconstrained, because the attributes worth
+    recording differ from one project to the next. The shape is not: a bare array,
+    string or number carries no field names, which leaves a Postgres key lookup
+    nothing to match and a published term nothing to map onto.
+    """
+    if not isinstance(value, dict):
+        raise ValidationError(
+            "Metadata must be a JSON object of key/value pairs, not %(json_type)s.",
+            code="invalid_metadata",
+            params={"json_type": _JSON_TYPE_NAMES.get(type(value), "a value of an unsupported type")},
+        )
+
+
+def metadata_field() -> models.JSONField:
+    """
+    Build the free-form metadata column that a model exposes to its owners.
+
+    Defined in one place so that the columns on different models cannot drift apart
+    in their default, their validation or the help text an API client reads.
+    """
+    return models.JSONField(
+        default=dict,
+        blank=True,
+        validators=[validate_metadata_object],
+        help_text=(
+            "Free-form JSON object holding attributes specific to this configuration, "
+            "beyond the fields modelled natively. Camera height or habitat description, "
+            "for example."
+        ),
+    )
+
+
 @final
 class Device(BaseModel):
     """
@@ -643,6 +691,7 @@ class Device(BaseModel):
     name = models.CharField(max_length=_POST_TITLE_MAX_LENGTH)
     description = models.TextField(blank=True)
     project = models.ForeignKey(Project, on_delete=models.SET_NULL, null=True, related_name="devices")
+    metadata = metadata_field()
 
     deployments: models.QuerySet["Deployment"]
 
@@ -770,6 +819,7 @@ class Deployment(BaseModel):
     latitude = models.FloatField(null=True, blank=True)
     longitude = models.FloatField(null=True, blank=True)
     image = models.ImageField(upload_to="deployments", blank=True, null=True)
+    metadata = metadata_field()
 
     project = models.ForeignKey(Project, on_delete=models.SET_NULL, null=True, related_name="deployments")
 

ami/main/tests.py

@@ -1,5 +1,6 @@
 import copy
 import datetime
+import json
 import logging
 import typing
 from io import BytesIO
@@ -8,7 +9,7 @@
 from django.conf import settings
 from django.contrib.auth.models import AnonymousUser
 from django.core.files.uploadedfile import SimpleUploadedFile
-from django.db import IntegrityError, connection, models
+from django.db import IntegrityError, connection, models, transaction
 from django.test import TestCase, override_settings
 from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
@@ -6599,6 +6600,199 @@ def test_non_integer_id_returns_400_not_500(self):
                 self.assertEqual(res.status_code, status.HTTP_400_BAD_REQUEST, f"{endpoint}?{param}=abc")
 
 
+class TestConfigurableMetadataFields(APITestCase):
+    """Free-form ``metadata`` on stations and device types.
+
+    Every project records attributes that Antenna does not model natively: the height a
+    camera was mounted at, a description of the habitat, the make of a light. Deployments
+    and device types each carry a ``metadata`` column for those. Its contents are
+    unconstrained, but its shape is not — it must be a JSON object, so that individual keys
+    stay queryable in Postgres and can be mapped onto a term when records are published.
+
+    These tests pin that an object survives a write and reads back unchanged, that a value
+    which is not an object is refused and leaves the stored value alone, that writing
+    metadata demands exactly the update permission the record already required, and that a
+    record created without metadata holds an empty object rather than null.
+    """
+
+    def setUp(self):
+        self.project = Project.objects.create(name="Metadata Project")
+        self.deployment = Deployment.objects.create(name="Metadata Deployment", project=self.project)
+        self.device = Device.objects.create(name="Metadata Device", project=self.project)
+
+        self.project_manager = User.objects.create_user(email="metadata_manager@insectai.org")
+        ProjectManager.assign_user(self.project_manager, self.project)
+        self.basic_member = User.objects.create_user(email="metadata_member@insectai.org")
+        BasicMember.assign_user(self.basic_member, self.project)
+
+        # Both models expose metadata on their detail endpoint, which is also the write path.
+        self.endpoints = {
+            "deployment": f"/api/v2/deployments/{self.deployment.pk}/",
+            "device": f"/api/v2/deployments/devices/{self.device.pk}/",
+        }
+
+    def test_metadata_object_round_trips(self):
+        """A nested object written through the API reads back exactly as it was sent."""
+        metadata = {
+            "camera_height_m": 2.5,
+            "habitat": "mixed deciduous woodland",
+            "lamp": {"type": "actinic", "watts": 15},
+            "visits": ["2026-05-01", "2026-06-01"],
+        }
+        self.client.force_authenticate(user=self.project_manager)
+
+        for name, endpoint in self.endpoints.items():
+            response = self.client.patch(endpoint, {"metadata": metadata}, format="json")
+            self.assertEqual(response.status_code, status.HTTP_200_OK, f"{name}: {response.content}")
+            self.assertEqual(response.json()["metadata"], metadata, name)
+
+            # Read it back on a fresh request: nesting, numbers and lists must all survive
+            # the round trip through the database rather than only the write response.
+            read_back = self.client.get(endpoint)
+            self.assertEqual(read_back.status_code, status.HTTP_200_OK, name)
+            self.assertEqual(read_back.json()["metadata"], metadata, name)
+
+    def test_non_object_metadata_is_rejected(self):
+        """An array, string, number or boolean is not metadata, and leaves the record untouched."""
+        self.client.force_authenticate(user=self.project_manager)
+
+        for name, endpoint in self.endpoints.items():
+            for value in ([1, 2, 3], "camera height 2.5m", 42, True):
+                response = self.client.patch(endpoint, {"metadata": value}, format="json")
+                self.assertEqual(
+                    response.status_code,
+                    status.HTTP_400_BAD_REQUEST,
+                    f"{name} accepted {value!r}",
+                )
+                self.assertIn("metadata", response.json(), f"{name} did not blame the metadata field")
+                # The message has to say what is wrong, because the browsable API and the
+                # Django admin show it to a person with no form validation in front of them.
+                self.assertIn("object", str(response.json()["metadata"]).lower(), name)
+
+        self.deployment.refresh_from_db()
+        self.device.refresh_from_db()
+        self.assertEqual(self.deployment.metadata, {})
+        self.assertEqual(self.device.metadata, {})
+
+    def test_metadata_write_requires_the_records_update_permission(self):
+        """Metadata follows the update permission each record already had, and adds none of its own."""
+        self.client.force_authenticate(user=self.basic_member)
+
+        for name, endpoint in self.endpoints.items():
+            # A basic member may read the record, so the refusal below is about writing.
+            self.assertEqual(self.client.get(endpoint).status_code, status.HTTP_200_OK, name)
+
+            response = self.client.patch(endpoint, {"metadata": {"habitat": "hedgerow"}}, format="json")
+            self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN, name)
+
+        self.deployment.refresh_from_db()
+        self.device.refresh_from_db()
+        self.assertEqual(self.deployment.metadata, {})
+        self.assertEqual(self.device.metadata, {})
+
+    def test_metadata_defaults_to_an_empty_object(self):
+        """A record created without metadata holds an empty object, and null is refused everywhere."""
+        deployment = Deployment.objects.create(name="Station without metadata", project=self.project)
+        device = Device.objects.create(name="Device without metadata", project=self.project)
+        self.assertEqual(deployment.metadata, {})
+        self.assertEqual(device.metadata, {})
+
+        self.client.force_authenticate(user=self.project_manager)
+        fresh_endpoints = {
+            "deployment": f"/api/v2/deployments/{deployment.pk}/",
+            "device": f"/api/v2/deployments/devices/{device.pk}/",
+        }
+        for name, endpoint in fresh_endpoints.items():
+            self.assertEqual(self.client.get(endpoint).json()["metadata"], {}, name)
+
+        # The column refuses null as well, so no code path can leave one behind for a
+        # reader to guard against.
+        for model in (Deployment, Device):
+            with self.assertRaises(IntegrityError, msg=model.__name__), transaction.atomic():
+                model.objects.create(name="Null metadata", project=self.project, metadata=None)
+
+    def test_null_is_refused_on_both_write_paths(self):
+        """Null is refused whichever way it arrives, by two different mechanisms.
+
+        A client serialiser emitting ``None`` for an absent value is the likeliest way a
+        null reaches this field by accident. Sent as JSON it never gets as far as the
+        shape check, because the field is not nullable and the framework stops it first.
+        Sent through the station form it arrives as the text ``null``, is parsed into
+        ``None``, and the shape check is what refuses it. Both are pinned, because a
+        change to either mechanism would leave the other still looking correct.
+        """
+        self.client.force_authenticate(user=self.project_manager)
+
+        for name, endpoint in self.endpoints.items():
+            response = self.client.patch(endpoint, {"metadata": None}, format="json")
+            self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST, name)
+            self.assertIn("metadata", response.json(), name)
+
+        response = self.client.patch(
+            self.endpoints["deployment"],
+            {"metadata": "null"},
+            format="multipart",
+        )
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST, response.content)
+        self.assertIn("null", str(response.json()["metadata"]).lower())
+
+        self.deployment.refresh_from_db()
+        self.device.refresh_from_db()
+        self.assertEqual(self.deployment.metadata, {})
+        self.assertEqual(self.device.metadata, {})
+
+    def test_station_metadata_survives_a_form_encoded_submission(self):
+        """A station is edited as a form, so its metadata arrives as JSON text and must be stored as an object.
+
+        The station form is submitted as multipart because the record carries a cover
+        image, and multipart has no JSON types. The value therefore reaches the serializer
+        as a string of JSON. Storing that string verbatim would look like a success and
+        only surface later, when a reader finds text where a mapping should be.
+        """
+        metadata = {"habitat": "mixed deciduous woodland", "camera_height_m": 2.5}
+        self.client.force_authenticate(user=self.project_manager)
+
+        response = self.client.patch(
+            self.endpoints["deployment"],
+            {"metadata": json.dumps(metadata)},
+            format="multipart",
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK, response.content)
+
+        self.deployment.refresh_from_db()
+        self.assertIsInstance(self.deployment.metadata, dict)
+        self.assertEqual(self.deployment.metadata, metadata)
+
+    def test_form_encoded_submission_is_held_to_the_same_shape_rule(self):
+        """The shape rule is enforced on the server, not only by the form that usually feeds it.
+
+        The station form refuses these five shapes before they leave the browser, but the
+        Django admin, the browsable API and any other client bypass that form entirely, so
+        each one is checked here against the endpoint itself.
+        """
+        self.client.force_authenticate(user=self.project_manager)
+
+        for value in ("[1, 2, 3]", '"a bare string"', "42", "true", "null"):
+            response = self.client.patch(
+                self.endpoints["deployment"],
+                {"metadata": value},
+                format="multipart",
+            )
+            self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST, f"accepted {value}")
+            self.assertIn("metadata", response.json(), f"{value} did not blame the metadata field")
+
+        # Text that is not JSON at all is refused too, rather than being stored as a string.
+        response = self.client.patch(
+            self.endpoints["deployment"],
+            {"metadata": "habitat: woodland"},
+            format="multipart",
+        )
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST, response.content)
+
+        self.deployment.refresh_from_db()
+        self.assertEqual(self.deployment.metadata, {})
+
+
 class TestDetectionNullMarker(TestCase):
     """
     Covers the null-marker abstraction added for Issue #1310 follow-up:

docs/claude/INDEX.md

@@ -40,6 +40,8 @@ archived.
 | `planning/celery-queue-split-rollout.md` | Rollout plan for the Celery queue split (`feat/celery-queue-split`) |
 | `planning/2026-05-28-captures-processed-filter-design.md` | Design: captures "Processed / Not processed" filter |
 | `planning/2026-05-28-captures-processed-filter-plan.md` | Implementation plan (checkbox tasks) for the captures processed filter |
+| `planning/2026-09-07-configurable-metadata-fields.md` | Free-form `metadata` JSON object on Deployment & Device (issue #507): why the shape is validated but the contents are not, why it differs from `Project.feature_flags`, detail-vs-list exposure, and what #307 still asks for. Keywords: metadata, JSONField, jsonb, GBIF, deployments, devices |
+| `planning/2026-09-07-configurable-metadata-fields-ui.md` | Frontend for issue #507: free-form JSON metadata field on the station and device-type forms. Text-not-object form value, validation helpers in `utils/fieldProcessors.ts`, multipart JSON seam. Keywords: metadata, JSON, forms, deployments, devices |
 
 ## Archive / session snapshots