ENH: tolerate unknown fields when decoding server JSON

When a client built against an older Tiled release talks to a newer server
that has added a field to a client-side dataclass (Asset, DataSource, Spec,
AwkwardStructure, TableStructure, ContainerStructure, ...), the client
previously crashed with `TypeError: unexpected keyword argument` because
`Structure.from_json`, `DataSource.from_json`, and `Spec(**...)` splatted the
payload directly into the dataclass.

Add a small `filter_known_kwargs` helper in `tiled.structures._compat` that
drops unknown keys and logs them at DEBUG. Wire it into `Structure.from_json`,
`Asset.from_json` (new), `DataSource.from_json`, and `Spec.from_json` (new),
and update the two `Spec(**spec)` call sites in `tiled.client.base` to use
`Spec.from_json`.

The server continues to strip fields for known-broken client versions via
the User-Agent gate, but this makes the client resilient to any future
additions without requiring a server-side back-compat entry.

Author: genematx

CHANGELOG.md

@@ -11,6 +11,11 @@ Write the date in place of the "Unreleased" in the case a new version is release
   from metadata responses when the request comes from a `python-tiled` client older than
   v0.2.13, whose `Asset` dataclass has no `size` field and would otherwise crash
   in `DataSource.from_json` with an unexpected keyword argument.
+- Tolerate unknown fields on the client side when decoding server JSON into
+  `Asset`, `DataSource`, `Spec`, and structure dataclasses (`AwkwardStructure`,
+  `TableStructure`, `ContainerStructure`). Unknown keys are dropped and logged
+  at DEBUG so a client can talk to a newer server without crashing on
+  fields it does not recognize.
 
 
 ## v0.2.13 (2026-07-08)

tests/test_structures_forward_compat.py

@@ -0,0 +1,81 @@
+"""Client-side tolerance for unknown fields in server JSON payloads."""
+
+import logging
+
+from tiled.structures.awkward import AwkwardStructure
+from tiled.structures.container import ContainerStructure
+from tiled.structures.core import Spec
+from tiled.structures.data_source import Asset, DataSource
+from tiled.structures.table import TableStructure
+
+
+def test_asset_from_json_tolerates_unknown_fields(caplog):
+    payload = {
+        "data_uri": "file:///tmp/x",
+        "is_directory": False,
+        "parameter": None,
+        "num": 0,
+        "id": 1,
+        "size": 42,
+        "future_field": "from a newer server",
+    }
+    with caplog.at_level(logging.DEBUG, logger="tiled.utils"):
+        asset = Asset.from_json(payload)
+    assert asset.data_uri == "file:///tmp/x"
+    assert asset.size == 42
+    assert "future_field" in caplog.text
+
+
+def test_data_source_from_json_tolerates_unknown_fields():
+    payload = {
+        "structure_family": "container",
+        "structure": None,
+        "id": 1,
+        "mimetype": "application/x-tiled-container",
+        "parameters": {},
+        "properties": {},
+        "assets": [
+            {
+                "data_uri": "file:///tmp/x",
+                "is_directory": False,
+                "parameter": None,
+                "size": 7,
+                "future_asset_field": "unknown",
+            }
+        ],
+        "management": "writable",
+        "future_ds_field": "unknown",
+    }
+    ds = DataSource.from_json(payload)
+    assert ds.mimetype == "application/x-tiled-container"
+    assert ds.assets[0].size == 7
+
+
+def test_spec_from_json_tolerates_unknown_fields():
+    spec = Spec.from_json({"name": "foo", "version": "1", "future_field": "unknown"})
+    assert spec.name == "foo"
+    assert spec.version == "1"
+
+
+def test_awkward_structure_from_json_tolerates_unknown_fields():
+    payload = {"length": 10, "form": {}, "future_field": "unknown"}
+    structure = AwkwardStructure.from_json(payload)
+    assert structure.length == 10
+
+
+def test_table_structure_from_json_tolerates_unknown_fields():
+    payload = {
+        "arrow_schema": "",
+        "npartitions": 1,
+        "columns": [],
+        "resizable": False,
+        "future_field": "unknown",
+    }
+    structure = TableStructure.from_json(payload)
+    assert structure.npartitions == 1
+
+
+def test_container_structure_from_json_tolerates_unknown_fields():
+    payload = {"keys": ["a", "b"], "future_field": "unknown"}
+    structure = ContainerStructure.from_json(payload)
+    assert list(structure.keys) == ["a", "b"]

tiled/client/base.py

@@ -259,7 +259,7 @@ def metadata_copy(self):
         validating metadata (useful with update_metadata())
         """
         metadata = deepcopy(self._item["attributes"]["metadata"])
-        specs = [Spec(**spec) for spec in self._item["attributes"]["specs"]]
+        specs = [Spec.from_json(spec) for spec in self._item["attributes"]["specs"]]
         access_tags = deepcopy(self._item["attributes"]["access_blob"].get("tags", []))
         return [
             md for md in [metadata, specs, access_tags] if md is not None
@@ -268,7 +268,9 @@ def metadata_copy(self):
     @property
     def specs(self) -> ListView[Spec]:
         "List of specifications describing the structure of the metadata and/or data."
-        return ListView([Spec(**spec) for spec in self._item["attributes"]["specs"]])
+        return ListView(
+            [Spec.from_json(spec) for spec in self._item["attributes"]["specs"]]
+        )
 
     @property
     def access_blob(self) -> DictView[str, JSON_ITEM]:
@@ -418,7 +420,7 @@ def raw_export(self, destination=None, max_workers=4, **kwargs):
             destination = kwargs.pop("destination_directory")
         if kwargs:
             raise TypeError(
-                f"raw_export() got unexpected keyword arguments: " f"{sorted(kwargs)!r}"
+                f"raw_export() got unexpected keyword arguments: {sorted(kwargs)!r}"
             )
 
         in_memory = isinstance(destination, MutableMapping)

tiled/structures/core.py

@@ -6,13 +6,14 @@
 
 import enum
 import importlib
+from collections.abc import Mapping
 from dataclasses import asdict, dataclass
-from typing import Dict, Optional
+from typing import Any, Dict, Optional
 
 from pydantic import StringConstraints
 from typing_extensions import Annotated
 
-from ..utils import OneShotCachedMap
+from ..utils import OneShotCachedMap, filter_known_kwargs
 
 
 class StructureFamily(str, enum.Enum):
@@ -50,30 +51,48 @@ def dict(self) -> Dict[str, Optional[str]]:
 
     model_dump = dict  # For easy interoperability with pydantic 2.x models
 
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> "Spec":
+        return cls(**filter_known_kwargs(cls, data))
+
 
 # TODO: make type[Structure] after #1036
 STRUCTURE_TYPES = OneShotCachedMap[StructureFamily, type](
     {
-        StructureFamily.array: lambda: importlib.import_module(
-            "...structures.array", StructureFamily.__module__
-        ).ArrayStructure,
-        StructureFamily.awkward: lambda: importlib.import_module(
-            "...structures.awkward", StructureFamily.__module__
-        ).AwkwardStructure,
-        StructureFamily.table: lambda: importlib.import_module(
-            "...structures.table", StructureFamily.__module__
-        ).TableStructure,
-        StructureFamily.sparse: lambda: importlib.import_module(
-            "...structures.sparse", StructureFamily.__module__
-        ).SparseStructure,
-        StructureFamily.ragged: lambda: importlib.import_module(
-            "...structures.ragged", StructureFamily.__module__
-        ).RaggedStructure,
-        StructureFamily.container: lambda: importlib.import_module(
-            "...structures.container", StructureFamily.__module__
-        ).ContainerStructure,
-        StructureFamily.bytes: lambda: importlib.import_module(
-            "...structures.bytes", StructureFamily.__module__
-        ).BytesStructure,
+        StructureFamily.array: lambda: (
+            importlib.import_module(
+                "...structures.array", StructureFamily.__module__
+            ).ArrayStructure
+        ),
+        StructureFamily.awkward: lambda: (
+            importlib.import_module(
+                "...structures.awkward", StructureFamily.__module__
+            ).AwkwardStructure
+        ),
+        StructureFamily.table: lambda: (
+            importlib.import_module(
+                "...structures.table", StructureFamily.__module__
+            ).TableStructure
+        ),
+        StructureFamily.sparse: lambda: (
+            importlib.import_module(
+                "...structures.sparse", StructureFamily.__module__
+            ).SparseStructure
+        ),
+        StructureFamily.ragged: lambda: (
+            importlib.import_module(
+                "...structures.ragged", StructureFamily.__module__
+            ).RaggedStructure
+        ),
+        StructureFamily.container: lambda: (
+            importlib.import_module(
+                "...structures.container", StructureFamily.__module__
+            ).ContainerStructure
+        ),
+        StructureFamily.bytes: lambda: (
+            importlib.import_module(
+                "...structures.bytes", StructureFamily.__module__
+            ).BytesStructure
+        ),
     }
 )

tiled/structures/data_source.py

@@ -5,6 +5,7 @@
 
 from tiled.structures.root import Structure
 
+from ..utils import filter_known_kwargs
 from .core import StructureFamily
 
 
@@ -24,6 +25,10 @@ class Asset:
     id: Optional[int] = None
     size: Optional[int] = None
 
+    @classmethod
+    def from_json(cls, data: Mapping[str, Any]) -> "Asset":
+        return cls(**filter_known_kwargs(cls, data))
+
 
 StructureT = TypeVar("StructureT", bound=Optional[Structure])
 
@@ -41,6 +46,6 @@ class DataSource(Generic[StructureT]):
 
     @classmethod
     def from_json(cls, structure: Mapping[str, Any]) -> "DataSource":
-        d = structure.copy()
-        assets = [Asset(**a) for a in d.pop("assets")]
-        return cls(assets=assets, **d)
+        d = dict(structure)
+        assets = [Asset.from_json(a) for a in d.pop("assets", [])]
+        return cls(assets=assets, **filter_known_kwargs(cls, d))

tiled/structures/root.py

@@ -2,9 +2,11 @@
 from collections.abc import Mapping
 from typing import Any
 
+from ..utils import filter_known_kwargs
+
 
 class Structure(ABC):
     @classmethod
     # TODO: When dropping support for Python 3.10 replace with -> Self
     def from_json(cls, structure: Mapping[str, Any]) -> "Structure":
-        return cls(**structure)
+        return cls(**filter_known_kwargs(cls, structure))

tiled/utils.py

@@ -2,10 +2,12 @@
 import builtins
 import collections.abc
 import contextlib
+import dataclasses
 import functools
 import importlib
 import importlib.util
 import inspect
+import logging
 import operator
 import os
 import platform
@@ -21,6 +23,43 @@
 import anyio
 import yaml
 
+logger = logging.getLogger(__name__)
+
+
+def filter_known_kwargs(target: Any, data: collections.abc.Mapping) -> dict:
+    """Return `data` restricted to keys that `target` accepts as kwargs.
+
+    `target` may be a dataclass (fields are consulted directly) or any other
+    callable (its signature is introspected). Keys dropped from `data` are
+    logged at DEBUG so a client talking to a newer server can be diagnosed
+    without failing.
+    """
+    if dataclasses.is_dataclass(target):
+        known = {f.name for f in dataclasses.fields(target)}
+    else:
+        params = inspect.signature(target).parameters
+        if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()):
+            return dict(data)
+        known = {
+            name
+            for name, p in params.items()
+            if p.kind
+            in (
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                inspect.Parameter.KEYWORD_ONLY,
+            )
+        }
+    filtered = {k: v for k, v in data.items() if k in known}
+    if dropped := set(data) - set(filtered):
+        name = getattr(target, "__name__", repr(target))
+        logger.debug(
+            "Ignoring unknown field(s) %s from server payload for %s; "
+            "the server is likely newer than this client.",
+            sorted(dropped),
+            name,
+        )
+    return filtered
+
 # helper for avoiding re-typing patch mimetypes
 # namedtuple for the lack of StrEnum in py<3.11
 patch_mimetypes = namedtuple(