datacontract-cli 1.0.11__tar.gz → 1.0.13__tar.gz

{datacontract_cli-1.0.11/datacontract_cli.egg-info → datacontract_cli-1.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacontract-cli
-Version: 1.0.11
+Version: 1.0.13
 Summary: The datacontract CLI is an open source command-line tool for working with Data Contracts. It uses data contract YAML files to lint the data contract, connect to data sources and execute schema and quality tests, detect breaking changes, and export to different formats. The tool is written in Python. It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a Python library.
 Author-email: Jochen Christ <jochen.christ@innoq.com>, Stefan Negele <stefan.negele@innoq.com>, Simon Harrer <simon.harrer@innoq.com>
 License-Expression: MIT
@@ -15,7 +15,7 @@ Requires-Dist: typer<0.27,>=0.18.0
 Requires-Dist: click<9.0.0,>=8.1.0
 Requires-Dist: pydantic<2.14.0,>=2.8.2
 Requires-Dist: pyyaml~=6.0.1
-Requires-Dist: ruamel.yaml<0.19,>=0.17
+Requires-Dist: ruamel.yaml<0.20,>=0.17
 Requires-Dist: requests<2.35,>=2.31
 Requires-Dist: truststore<1.0,>=0.10
 Requires-Dist: fastjsonschema<2.22.0,>=2.19.1
@@ -94,7 +94,7 @@ Provides-Extra: rdf
 Requires-Dist: rdflib==7.6.0; extra == "rdf"
 Provides-Extra: api
 Requires-Dist: fastapi<0.140.0,>=0.115.0; extra == "api"
-Requires-Dist: uvicorn<0.51.0,>=0.44.0; extra == "api"
+Requires-Dist: uvicorn<0.52.0,>=0.44.0; extra == "api"
 Provides-Extra: protobuf
 Requires-Dist: proto-schema-parser<3.0,>=1.0; extra == "protobuf"
 Provides-Extra: all
@@ -112,7 +112,7 @@ Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: pymssql==2.3.13; extra == "dev"
 Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "dev"
 Requires-Dist: mysql-connector-python<9.7.0,>=8.0.30; extra == "dev"
-Requires-Dist: ruff==0.15.20; extra == "dev"
+Requires-Dist: ruff==0.15.21; extra == "dev"
 Requires-Dist: testcontainers[kafka,minio,mssql,mysql,postgres]==4.14.2; extra == "dev"
 Requires-Dist: trino==0.338.0; extra == "dev"
 Dynamic: license-file

{datacontract_cli-1.0.11 → datacontract_cli-1.0.13}/datacontract/engines/checks/check_spec.py

@@ -30,6 +30,7 @@ class MetricType(str, Enum):
     FIELD_PRESENT = "field_present"
     FIELD_TYPE = "field_type"
     FIELD_PHYSICAL_TYPE = "field_physical_type"
+    FIELD_NESTED_TYPE = "field_nested_type"
     FRESHNESS = "freshness"
     RETENTION = "retention"
     CUSTOM_SQL = "custom_sql"

{datacontract_cli-1.0.11 → datacontract_cli-1.0.13}/datacontract/engines/checks/create_checks.py

@@ -22,6 +22,7 @@ from open_data_contract_standard.model import (
 )
 
 from datacontract.engines.checks.check_spec import CheckSpec, MetricType, Op, Threshold
+from datacontract.engines.checks.type_normalize import normalize_type_name
 from datacontract.engines.ibis.native_type import supports_native_type_introspection
 
 logger = logging.getLogger(__name__)
@@ -54,6 +55,51 @@ def to_schema_name(schema_object: SchemaObject, server_type: Optional[str]) -> s
     return schema_object.name
 
 
+def _scalar_element_type(prop: SchemaProperty, physical: bool) -> Optional[str]:
+    """The declared element type of an array of scalars, or None for anything else."""
+    if normalize_type_name(prop.logicalType or prop.physicalType) != "array" or prop.items is None:
+        return None
+    items = prop.items
+    if items.properties or items.items is not None:
+        return None
+    label = (items.physicalType or items.logicalType) if physical else (items.logicalType or items.physicalType)
+    if normalize_type_name(label) in ("object", "array"):
+        return None
+    return label
+
+
+def _declared_type_label(prop: SchemaProperty, physical: bool) -> Optional[str]:
+    """Render the declared type with its children, e.g. ``OBJECT(code VARCHAR(10), description VARCHAR)``."""
+    label = (prop.physicalType or prop.logicalType) if physical else (prop.logicalType or prop.physicalType)
+    base = normalize_type_name(label)
+    if base == "array" and prop.items is not None:
+        return f"{label}({_declared_type_label(prop.items, physical)})"
+    if base == "object" and prop.properties:
+        children = ", ".join(f"{child.name} {_declared_type_label(child, physical)}" for child in prop.properties)
+        return f"{label}({children})"
+    return label
+
+
+def _nested_type_check(model: str, field: str, prop: SchemaProperty, physical: bool) -> CheckSpec:
+    check_type = "field_nested_physical_type" if physical else "field_nested_type"
+    element = _scalar_element_type(prop, physical)
+    if element is not None:
+        name = f"Check that items of array {field} have {'physical type' if physical else 'type'} {element}"
+    else:
+        name = f"Check that nested {'physical types' if physical else 'types'} of {field} are correct"
+    return CheckSpec(
+        key=f"{model}__{field}__{check_type}",
+        category="schema",
+        type=check_type,
+        name=name,
+        model=model,
+        field=field,
+        metric=MetricType.FIELD_NESTED_TYPE,
+        expected_type_label=_declared_type_label(prop, physical),
+        expected_schema_property=prop,
+    )
+
+
 _PERCENT_UNITS = {"percent", "percentage", "%"}
 
 
@@ -172,6 +218,20 @@ def _to_schema_checks(schema_object: SchemaObject, server: Optional[Server]) ->
             )
         )
 
+        # The raw view cannot provide nested type checks
+        declared_base = normalize_type_name(prop.logicalType or prop.physicalType)
+        nested_checks_possible = (
+            check_types
+            and not uses_raw_view
+            and declared_base in ("object", "array")
+            and (bool(prop.properties) or prop.items is not None)
+        )
+        base_prop = (
+            SchemaProperty(name=prop.name, logicalType=prop.logicalType, physicalType=prop.physicalType)
+            if nested_checks_possible
+            else prop
+        )
+
         # A declared physicalType is checked against the column's real native
         # type in the platform catalog and takes precedence over logicalType,
         # but only on backends that expose a meaningful native type. Elsewhere
@@ -191,11 +251,13 @@ def _to_schema_checks(schema_object: SchemaObject, server: Optional[Server]) ->
                     expected_physical_type=prop.physicalType,
                     # Carried for the logicalType fallback when the native type
                     # cannot be read or the physicalType is cross-dialect.
-                    expected_schema_property=prop if prop.logicalType is not None else None,
+                    expected_schema_property=base_prop if prop.logicalType is not None else None,
                 )
             )
+            if nested_checks_possible:
+                checks.append(_nested_type_check(model, field, prop, physical=True))
         elif check_types and prop.logicalType is not None:
-            schema_prop, label = prop, prop.logicalType or ""
+            label = prop.logicalType or ""
             checks.append(
                 CheckSpec(
                     key=f"{model}__{field}__field_type",
@@ -207,9 +269,11 @@ def _to_schema_checks(schema_object: SchemaObject, server: Optional[Server]) ->
                     metric=MetricType.FIELD_TYPE,
                     expected_category=label,
                     expected_type_label=label,
-                    expected_schema_property=schema_prop,
+                    expected_schema_property=base_prop,
                 )
             )
+            if nested_checks_possible:
+                checks.append(_nested_type_check(model, field, prop, physical=False))
 
         if prop.required:
             checks.append(

{datacontract_cli-1.0.11 → datacontract_cli-1.0.13}/datacontract/engines/checks/physical_type_match.py

@@ -43,6 +43,31 @@ def _timestamp_family() -> set:
 
 _TIMESTAMP_FAMILY = _timestamp_family()
 
+# Each group is a single Snowflake type under different names, which its catalog
+# reports as the one canonical name (TEXT, NUMBER, FLOAT), so a contract declaring
+# any of the aliases must match its own column. Dialect-specific because elsewhere
+# (MySQL, SQL Server) TEXT and VARCHAR, or INT and DECIMAL, are distinct types.
+_SNOWFLAKE_FAMILIES = (
+    {exp.DataType.Type.VARCHAR, exp.DataType.Type.TEXT, exp.DataType.Type.NVARCHAR},
+    # exact numerics: INT/INTEGER/BIGINT/SMALLINT/TINYINT/BYTEINT/NUMERIC are NUMBER(38,0)
+    {
+        exp.DataType.Type.DECIMAL,
+        exp.DataType.Type.INT,
+        exp.DataType.Type.BIGINT,
+        exp.DataType.Type.SMALLINT,
+        exp.DataType.Type.TINYINT,
+    },
+    # approximate numerics: FLOAT/FLOAT4/FLOAT8/DOUBLE/REAL are all 64-bit FLOAT
+    {exp.DataType.Type.DOUBLE, exp.DataType.Type.FLOAT},
+)
+
+
+def _is_snowflake(dialect) -> bool:
+    if isinstance(dialect, str):
+        return dialect.lower() == "snowflake"
+    name = getattr(dialect, "__name__", None) or type(dialect).__name__
+    return name.lower() == "snowflake"
+
 
 def _parse(type_str: str, dialect) -> Optional[exp.DataType]:
     """Parse a type string into an ``exp.DataType`` for ``dialect``, or ``None``."""
@@ -132,12 +157,14 @@ def physical_type_matches(
         exp_dt.this == act_dt.this
         or {exp_dt.this, act_dt.this} <= _TIMESTAMP_FAMILY
         or (both_numeric and _base_sql(exp_dt, dialect) == _base_sql(act_dt, dialect))
+        or (_is_snowflake(dialect) and any({exp_dt.this, act_dt.this} <= family for family in _SNOWFLAKE_FAMILIES))
     )
     if not same_base:
         return False, f"expected physical type '{expected}' but the column is '{actual}'"
 
-    expected_params = _params(exp_dt)
-    if expected_params and expected_params != _params(act_dt):
+    # sqlglot fills in a dialect's default precision (a bare NUMBER parses as
+    # DECIMAL(38,0)), so what the contract declares is read off the raw string.
+    if _split_base(_normalize_raw(expected))[1] and _params(exp_dt) != _params(act_dt):
         return False, f"expected physical type '{expected}' but the column is '{actual}'"
 
     return True, ""

{datacontract_cli-1.0.11 → datacontract_cli-1.0.13}/datacontract/engines/checks/type_normalize.py

@@ -11,9 +11,19 @@ the actual type is structurally compatible with the expected one.
 from __future__ import annotations
 
 import re
+from typing import NamedTuple
 
 from open_data_contract_standard.model import SchemaProperty
 
+from datacontract.engines.checks.physical_type_match import physical_type_matches
+
+# logicalType marker for a field whose type the backend cannot describe: a
+# dynamically-typed column (ibis json: Snowflake VARIANT, Postgres JSONB,
+# BigQuery JSON) or an unsupported one (binary, geography). No declared type can
+# be confirmed against it, so any expected type fails rather than silently passing.
+# Distinct from a missing field, which is what dropping it would look like.
+UNKNOWN_LOGICAL_TYPE = "__unknown__"
+
 
 def normalize_type_name(type_name: str | None) -> str | None:
     """Map a contract type name (logical or physical) to one of the 9 ODCS categories.
@@ -139,6 +149,8 @@ def schema_property_matches(expected: SchemaProperty | None, actual: SchemaPrope
     if expected_base is None:
         return True
     if actual_base is None:
+        # actual is unsupported or dynamically typed (json element/variant): a
+        # declared concrete type can't be confirmed against it, so it fails.
         return False
     if expected_base != actual_base and not (expected_base in _NUMERIC and actual_base in _NUMERIC):
         return False
@@ -151,6 +163,8 @@ def schema_property_matches(expected: SchemaProperty | None, actual: SchemaPrope
     if expected_base == "object":
         if not expected.properties:
             return True
+        # actual.properties is None for an untyped object (ibis map/variant): the
+        # empty lookup below fails every declared field, which is what we want.
         actual_by_name = {p.name.lower(): p for p in (actual.properties or []) if p.name}
         for exp_field in expected.properties:
             if not exp_field.name:
@@ -165,29 +179,42 @@ def schema_property_matches(expected: SchemaProperty | None, actual: SchemaPrope
     return True
 
 
-def schema_property_mismatch_reason(
-    expected: SchemaProperty | None,
-    actual: SchemaProperty | None,
-    path: str = "",
-) -> str:
-    """Return a human-readable description of the first structural mismatch and a count of other type errors, or '' if none."""
-    errors = schema_property_mismatch_reasons(expected, actual, path)
+class TypeMismatch(NamedTuple):
+    message: str
+    # False when the actual structure cannot be read (json / variant / untyped
+    # object): the declared type is neither confirmed nor refuted.
+    verifiable: bool
+
+
+def format_mismatch_reason(errors: list[TypeMismatch]) -> str:
+    """The first mismatch and a count of the other type errors, or '' if none."""
     num_errors = len(errors)
 
     if num_errors == 0:
         return ""
     elif num_errors == 1:
-        return errors[0]
+        return errors[0].message
     else:
-        return f"{errors[0]} (and {num_errors - 1} other error{'s' if num_errors > 2 else ''})"
+        return f"{errors[0].message} (and {num_errors - 1} other error{'s' if num_errors > 2 else ''})"
+
+
+def schema_property_mismatch_reason(
+    expected: SchemaProperty | None,
+    actual: SchemaProperty | None,
+    path: str = "",
+    dialect=None,
+) -> str:
+    """Return a human-readable description of the first structural mismatch and a count of other type errors, or '' if none."""
+    return format_mismatch_reason(schema_property_mismatch_reasons(expected, actual, path, dialect))
 
 
 def schema_property_mismatch_reasons(
     expected: SchemaProperty | None,
     actual: SchemaProperty | None,
     path: str = "",
-) -> list[str]:
-    errors: list[str] = []
+    dialect=None,
+) -> list[TypeMismatch]:
+    errors: list[TypeMismatch] = []
 
     if expected is None:
         return errors
@@ -195,29 +222,73 @@ def schema_property_mismatch_reasons(
     field_label = f"field '{path}'" if path else "column"
     if actual is None:
         exp_str = expected.logicalType or expected.physicalType
-        errors.append(f"{field_label}: expected type '{exp_str}' but the column type could not be determined")
+        errors.append(
+            TypeMismatch(
+                f"{field_label}: expected type '{exp_str}' but the column type could not be determined",
+                verifiable=False,
+            )
+        )
         return errors
-
     expected_base = normalize_type_name(expected.logicalType or expected.physicalType)
     actual_base = normalize_type_name(actual.logicalType or actual.physicalType)
 
     if expected_base is None:
         return errors
 
+    if actual_base is None:
+        exp_str = expected.logicalType or expected.physicalType
+        act_str = actual.physicalType or "unknown"
+        errors.append(
+            TypeMismatch(
+                f"{field_label}: has type '{act_str}', but the contract specifies '{exp_str}'. "
+                f"A '{act_str}' value has no verifiable logical type. "
+                f"If this is intentional, specify `physicalType: {act_str}`.",
+                verifiable=False,
+            )
+        )
+        return errors
+
+    # A leaf that declares a physicalType is compared against the column's real
+    # native type, where the backend reports one. The declared type wins over the
+    # logicalType, as it does for the column itself.
+    if expected_base not in ("object", "array") and expected.physicalType and actual.physicalType:
+        result, reason = physical_type_matches(expected.physicalType, actual.physicalType, dialect)
+        if result is True:
+            return errors
+        if result is False:
+            errors.append(TypeMismatch(f"{field_label}: {reason}", verifiable=True))
+            return errors
+        # The declared type names nothing in this dialect (a logical keyword such
+        # as `string`, or a type from another platform): fall back to the category
+        # comparison, and only give up when there is no logicalType to fall back on.
+        if expected.logicalType is None:
+            errors.append(TypeMismatch(f"{field_label}: {reason}", verifiable=False))
+            return errors
+
     if expected_base != actual_base and not (expected_base in _NUMERIC and actual_base in _NUMERIC):
         exp_str = expected.logicalType or expected.physicalType
         act_str = actual.logicalType or actual.physicalType
-        errors.append(f"{field_label}: expected type '{exp_str}' but got '{act_str}'")
+        errors.append(TypeMismatch(f"{field_label}: expected type '{exp_str}' but got '{act_str}'", verifiable=True))
         return errors
 
     if expected_base == "array":
         if expected.items is not None:
             child_path = f"{path}[]" if path else "[]"
-            errors.extend(schema_property_mismatch_reasons(expected.items, actual.items, child_path))
+            errors.extend(schema_property_mismatch_reasons(expected.items, actual.items, child_path, dialect))
 
     if expected_base == "object":
         if not expected.properties:
             return errors
+        if actual.properties is None:
+            errors.append(
+                TypeMismatch(
+                    f"{field_label}: nested properties are declared but the column is an untyped object "
+                    "whose structure can't be verified. Use a structured type for your data or specify "
+                    "physicalType.",
+                    verifiable=False,
+                )
+            )
+            return errors
 
         actual_by_name = {p.name.lower(): p for p in (actual.properties or []) if p.name}
         for exp_field in expected.properties:
@@ -228,9 +299,9 @@ def schema_property_mismatch_reasons(
             act_field = actual_by_name.get(exp_field.name.lower())
 
             if act_field is None:
-                errors.append(f"field '{child_path}' is missing")
+                errors.append(TypeMismatch(f"field '{child_path}' is missing", verifiable=True))
                 continue
 
-            errors.extend(schema_property_mismatch_reasons(exp_field, act_field, child_path))
+            errors.extend(schema_property_mismatch_reasons(exp_field, act_field, child_path, dialect))
 
     return errors

{datacontract_cli-1.0.11 → datacontract_cli-1.0.13}/datacontract/engines/ibis/dtype_category.py

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING
 
 from open_data_contract_standard.model import SchemaProperty
 
+from datacontract.engines.checks.type_normalize import UNKNOWN_LOGICAL_TYPE
+
 if TYPE_CHECKING:
     from ibis.expr.datatypes import DataType
 
@@ -48,13 +50,14 @@ def ibis_dtype_category(dtype) -> str:
     return "other"
 
 
-def ibis_dtype_to_schema_property(dtype: DataType) -> SchemaProperty | None:
+def ibis_dtype_to_schema_property(dtype: DataType) -> SchemaProperty:
     """Map an ibis DataType to a SchemaProperty for structural type comparison.
 
     Returns a ``SchemaProperty`` with ``logicalType`` set to one of the 9 ODCS
     categories, recursively populating ``properties`` for structs and ``items``
-    for arrays. Returns ``None`` for unsupported types (binary, map, null, etc.)
-    so the caller can skip comparison rather than raising a false failure.
+    for arrays. A type that carries no verifiable logical type (json, binary,
+    null, …) becomes ``UNKNOWN_LOGICAL_TYPE`` with the actual type kept in
+    ``physicalType``, so the failure message can name it.
     """
     try:
         if dtype.is_boolean():
@@ -74,20 +77,25 @@ def ibis_dtype_to_schema_property(dtype: DataType) -> SchemaProperty | None:
         if dtype.is_struct():
             properties = []
             for field_name, ftype in dtype.fields.items():
+                # an unverifiable field type is still a field: keep it, so it is not reported missing
                 child = ibis_dtype_to_schema_property(ftype)
-                if child is not None:
-                    properties.append(
-                        SchemaProperty(
-                            name=field_name,
-                            logicalType=child.logicalType,
-                            items=child.items,
-                            properties=child.properties,
-                        )
+                properties.append(
+                    SchemaProperty(
+                        name=field_name,
+                        logicalType=child.logicalType,
+                        physicalType=child.physicalType,
+                        items=child.items,
+                        properties=child.properties,
                     )
-            return SchemaProperty(logicalType="object", properties=properties if properties else None)
+                )
+            return SchemaProperty(logicalType="object", properties=properties)
         if dtype.is_array():
             element = ibis_dtype_to_schema_property(dtype.value_type)
             return SchemaProperty(logicalType="array", items=element)
+        if dtype.is_map():
+            # base is confirmable, inner values are not (yet)
+            return SchemaProperty(logicalType="object", properties=None)
     except AttributeError:
-        return None
-    return None
+        return SchemaProperty(logicalType=UNKNOWN_LOGICAL_TYPE)
+    # json holds a different type per row; binary and null have no ODCS category
+    return SchemaProperty(logicalType=UNKNOWN_LOGICAL_TYPE, physicalType=str(dtype))

{datacontract_cli-1.0.11 → datacontract_cli-1.0.13}/datacontract/engines/ibis/ibis_check_execute.py

@@ -14,14 +14,21 @@ import uuid
 from collections import defaultdict
 from typing import List, Optional
 
-from open_data_contract_standard.model import OpenDataContractStandard, Server
+from open_data_contract_standard.model import OpenDataContractStandard, SchemaProperty, Server
 
 from datacontract.engines.checks.check_spec import CheckSpec, MetricType
 from datacontract.engines.checks.physical_type_match import physical_type_matches
-from datacontract.engines.checks.type_normalize import schema_property_matches, schema_property_mismatch_reason
+from datacontract.engines.checks.type_normalize import (
+    format_mismatch_reason,
+    normalize_type_name,
+    schema_property_matches,
+    schema_property_mismatch_reason,
+    schema_property_mismatch_reasons,
+)
 from datacontract.engines.ibis.connections.connect import connect_ibis
 from datacontract.engines.ibis.dtype_category import ibis_dtype_to_schema_property
 from datacontract.engines.ibis.native_type import fetch_native_types, sqlglot_dialect
+from datacontract.engines.ibis.snowflake_structured_types import fetch_structured_types, has_nesting
 from datacontract.model.exceptions import DataContractException
 from datacontract.model.run import Check, ResultEnum, Run
 from datacontract.model.server import get_server_type
@@ -62,6 +69,8 @@ def _describe(spec: CheckSpec) -> str:
         return f"type({spec.field}) == {spec.expected_type_label}"
     if spec.metric == MetricType.FIELD_PHYSICAL_TYPE:
         return f"physical_type({spec.field}) == {spec.expected_physical_type}"
+    if spec.metric == MetricType.FIELD_NESTED_TYPE:
+        return f"nested_types({spec.field}) match the contract"
     if spec.metric == MetricType.FIELD_PRESENT:
         return f"present({spec.field})"
     if spec.threshold is not None:
@@ -196,6 +205,15 @@ def _run_model(
     if any(spec.metric == MetricType.FIELD_PHYSICAL_TYPE for spec in specs):
         native_types = fetch_native_types(con, server, model)
 
+    # Snowflake collapses structured OBJECT/ARRAY nesting in the ibis dtype; read
+    # the real nested types from SHOW COLUMNS so field_type checks can recurse.
+    structured_types = None
+    if get_server_type(server) == "snowflake" and any(
+        spec.metric in (MetricType.FIELD_TYPE, MetricType.FIELD_PHYSICAL_TYPE, MetricType.FIELD_NESTED_TYPE)
+        for spec in specs
+    ):
+        structured_types = fetch_structured_types(con, server, t.get_name())
+
     agg_exprs = []  # list[(spec, named_expr)]
     for spec in specs:
         try:
@@ -219,9 +237,11 @@ def _run_model(
             elif spec.metric == MetricType.FIELD_PRESENT:
                 _run_present(run, con, model, columns, spec)
             elif spec.metric == MetricType.FIELD_TYPE:
-                _run_type(run, schema, columns, spec)
+                _run_type(run, schema, columns, spec, structured_types)
             elif spec.metric == MetricType.FIELD_PHYSICAL_TYPE:
-                _run_physical_type(run, con, server, schema, columns, native_types, spec)
+                _run_physical_type(run, con, server, schema, columns, native_types, spec, structured_types)
+            elif spec.metric == MetricType.FIELD_NESTED_TYPE:
+                _run_nested_type(run, schema, columns, spec, structured_types, sqlglot_dialect(con))
             elif spec.metric in (MetricType.FRESHNESS, MetricType.RETENTION):
                 _run_freshness(run, t, columns, spec)
             elif spec.metric == MetricType.CUSTOM_SQL:
@@ -615,7 +635,7 @@ def _run_present(run: Run, con, model: str, columns, spec: CheckSpec):
     )
 
 
-def _run_type(run: Run, schema, columns, spec: CheckSpec):
+def _run_type(run: Run, schema, columns, spec: CheckSpec, structured_types: dict[str, SchemaProperty] | None = None):
     _set_impl(
         run,
         spec.key,
@@ -628,11 +648,19 @@ def _run_type(run: Run, schema, columns, spec: CheckSpec):
         _set_result(run, spec.key, ResultEnum.failed, f"Column '{spec.field}' is missing")
         return
     dtype = schema[actual_col]
-    actual_prop = ibis_dtype_to_schema_property(dtype)
+    # Snowflake structured types come back collapsed from ibis; prefer the nested
+    # tree recovered from SHOW COLUMNS when available.
+    structured_prop = structured_types.get(spec.field.lower()) if structured_types else None
+    actual_prop = structured_prop or ibis_dtype_to_schema_property(dtype)
     _set_diagnostics(
         run,
         spec.key,
-        _diag(metric="field_type", field=spec.field, expected=spec.expected_type_label, actual=str(dtype)),
+        _diag(
+            metric="field_type",
+            field=spec.field,
+            expected=spec.expected_type_label,
+            actual=structured_prop.physicalType if structured_prop else str(dtype),
+        ),
     )
     if schema_property_matches(spec.expected_schema_property, actual_prop):
         _set_result(run, spec.key, ResultEnum.passed, None)
@@ -646,7 +674,16 @@ def _run_type(run: Run, schema, columns, spec: CheckSpec):
         )
 
 
-def _run_physical_type(run: Run, con, server, schema, columns, native_types, spec: CheckSpec):
+def _run_physical_type(
+    run: Run,
+    con,
+    server,
+    schema,
+    columns,
+    native_types,
+    spec: CheckSpec,
+    structured_types: dict[str, SchemaProperty] | None = None,
+):
     """Compare a column's real native type against the contract's physicalType.
 
     When the native type cannot be read for this backend, or the declared
@@ -668,7 +705,13 @@ def _run_physical_type(run: Run, con, server, schema, columns, native_types, spe
         _set_result(run, spec.key, ResultEnum.failed, f"Column '{spec.field}' is missing")
         return
 
-    actual_native = native_types.get(spec.field.lower()) if native_types else None
+    # The catalog reports a structured OBJECT/ARRAY as its bare token, dropping the
+    # nested types; the tree recovered from SHOW COLUMNS renders the real native type.
+    structured_prop = structured_types.get(spec.field.lower()) if structured_types else None
+    if structured_prop is not None and has_nesting(structured_prop):
+        actual_native = structured_prop.physicalType
+    else:
+        actual_native = native_types.get(spec.field.lower()) if native_types else None
     _set_diagnostics(
         run,
         spec.key,
@@ -697,22 +740,91 @@ def _run_physical_type(run: Run, con, server, schema, columns, native_types, spe
     # logicalType category check when the property declares one.
     fallback = spec.expected_schema_property
     if fallback is not None and fallback.logicalType is not None:
-        actual_prop = ibis_dtype_to_schema_property(schema[actual_col])
+        actual_prop = structured_prop or ibis_dtype_to_schema_property(schema[actual_col])
         if schema_property_matches(fallback, actual_prop):
             _set_result(run, spec.key, ResultEnum.passed, None)
         else:
             mismatch = schema_property_mismatch_reason(fallback, actual_prop)
+            actual_label = actual_native or schema[actual_col]
             _set_result(
                 run,
                 spec.key,
                 ResultEnum.failed,
-                mismatch or f"Expected type '{fallback.logicalType}' but column is '{schema[actual_col]}'",
+                mismatch or f"Expected type '{fallback.logicalType}' but column is '{actual_label}'",
             )
         return
 
     _set_result(run, spec.key, ResultEnum.warning, f"{reason}; skipping the physical type check")
 
 
+def _run_nested_type(
+    run: Run,
+    schema,
+    columns,
+    spec: CheckSpec,
+    structured_types: dict[str, SchemaProperty] | None = None,
+    dialect=None,
+):
+    """Compare the children a property declares (``properties:`` / ``items:``) against
+    the column's real nested structure. The column's own type is the base check's job.
+    """
+    metric = spec.type
+    _set_impl(run, spec.key, f"nested types of '{spec.field}' match the contract", "introspection")
+    actual_col = columns.get(spec.field.lower())
+    if actual_col is None:
+        _set_diagnostics(run, spec.key, _diag(metric=metric, field=spec.field, expected=spec.expected_type_label))
+        _set_result(run, spec.key, ResultEnum.failed, f"Column '{spec.field}' is missing")
+        return
+
+    dtype = schema[actual_col]
+    structured_prop = structured_types.get(spec.field.lower()) if structured_types else None
+    actual_prop = structured_prop or ibis_dtype_to_schema_property(dtype)
+    actual_label = (structured_prop.physicalType if structured_prop else None) or str(dtype)
+    _set_diagnostics(
+        run,
+        spec.key,
+        _diag(metric=metric, field=spec.field, expected=spec.expected_type_label, actual=actual_label),
+    )
+
+    expected = spec.expected_schema_property
+    expected_base = normalize_type_name(expected.logicalType or expected.physicalType)
+    actual_base = normalize_type_name(actual_prop.logicalType or actual_prop.physicalType)
+    if actual_base is None:
+        # A dynamically-typed column (json / variant / jsonb) holds a different
+        # structure per row, so there is nothing to compare the children against.
+        _set_result(
+            run,
+            spec.key,
+            ResultEnum.warning,
+            f"The structure of the '{actual_label}' column '{spec.field}' cannot be read; "
+            f"skipping the nested type check",
+        )
+        return
+    if expected_base != actual_base:
+        # The base type check names the actual type; repeating it here would print
+        # the column's whole rendered structure.
+        _set_result(
+            run,
+            spec.key,
+            ResultEnum.failed,
+            f"Cannot verify the nested types of '{spec.field}': the column is not an {expected_base}",
+        )
+        return
+
+    errors = schema_property_mismatch_reasons(expected, actual_prop, spec.field, dialect)
+    if not errors:
+        _set_result(run, spec.key, ResultEnum.passed, None)
+        return
+    _update_diagnostics(run, spec.key, {"errors": [error.message for error in errors]})
+    verified = any(error.verifiable for error in errors)
+    _set_result(
+        run,
+        spec.key,
+        ResultEnum.failed if verified else ResultEnum.warning,
+        format_mismatch_reason(errors),
+    )
+
+
 def _run_freshness(run: Run, t, columns, spec: CheckSpec):
     import pandas as pd