Scope carousel list items and bump version

Author: ziodave

AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS
+
+## Project Notes
+
+- Generated Google SHACLs scope `ListItem` requirements under `ItemList` when both types
+  appear in a feature definition, preventing carousel constraints from firing on
+  `BreadcrumbList`.

README.md

@@ -90,6 +90,10 @@ Override the web page import callback by placing `web_page_import_protocol.py` w
 
 Add `.ttl.liquid` files under `data/templates`. Templates render with `account` fields available (e.g., `{{ account.dataset_uri }}`) and are uploaded before URL handling begins.
 
+## Validation
+
+SHACL validation utilities and generated Google Search Gallery shapes are included. Carousel `ListItem` requirements are scoped under `ItemList` when both types are present to avoid enforcing carousel constraints on non-carousel lists (for example, `BreadcrumbList`).
+
 ## Testing
 
 ```bash
@@ -100,4 +104,3 @@ poetry run pytest
 ## Documentation
 
 - [Google Sheets Lookup](docs/google_sheets_lookup.md): Utility for O(1) lookups from Google Sheets.
-

TODO.md

@@ -0,0 +1,4 @@
+# TODO
+
+- [x] 2026-02-04 Scope carousel `ListItem` constraints under `ItemList` in the SHACL generator.
+- [x] 2026-02-04 Replace deprecated `datetime.utcnow()` with timezone-aware UTC timestamps.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wordlift-sdk"
-version = "2.10.3"
+version = "2.11.0"
 description = ""
 authors = ["David Riccitelli <david@wordlift.io>"]
 readme = "README.md"

specs/validation.md

@@ -0,0 +1,8 @@
+# Validation Specs
+
+## Google Search Gallery SHACLs
+
+When a Google Search Gallery feature includes both `ItemList` and `ListItem` requirements,
+`ListItem` constraints are scoped under `ItemList` via `itemListElement` instead of
+targeting `ListItem` globally. This prevents carousel rules from applying to unrelated
+lists such as `BreadcrumbList`.

tests/test_shacl_generator.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+
+from wordlift_sdk.validation.generator import FeatureData, _write_feature
+
+
+def _read_output(tmp_path: Path, feature: FeatureData) -> str:
+    output_path = tmp_path / "google-carousel.ttl"
+    assert _write_feature(feature, output_path, overwrite=True)
+    return output_path.read_text(encoding="utf-8")
+
+
+def test_scopes_listitem_under_itemlist(tmp_path: Path) -> None:
+    feature = FeatureData(
+        url="https://example.com",
+        types={
+            "ItemList": {"required": {"itemListElement"}, "recommended": set()},
+            "ListItem": {
+                "required": {"position", "url", "name", "item"},
+                "recommended": set(),
+            },
+        },
+    )
+
+    content = _read_output(tmp_path, feature)
+
+    assert "sh:targetClass schema:ItemList" in content
+    assert "sh:targetClass schema:ListItem" not in content
+    assert "sh:path schema:itemListElement" in content
+    assert "sh:node [" in content
+    assert "sh:class schema:ListItem" in content
+    assert "sh:path schema:url" in content
+
+
+def test_keeps_listitem_shape_without_itemlist(tmp_path: Path) -> None:
+    feature = FeatureData(
+        url="https://example.com",
+        types={
+            "ListItem": {
+                "required": {"position", "url"},
+                "recommended": set(),
+            }
+        },
+    )
+
+    content = _read_output(tmp_path, feature)
+
+    assert "sh:targetClass schema:ListItem" in content

wordlift_sdk/validation/generator.py

@@ -6,7 +6,7 @@
 import html as html_lib
 import re
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Iterable
 
@@ -173,6 +173,10 @@ def _write_feature(feature: FeatureData, output_path: Path, overwrite: bool) ->
     if output_path.exists() and not overwrite:
         return False
 
+    scoped_list_item = None
+    if "ItemList" in feature.types and "ListItem" in feature.types:
+        scoped_list_item = feature.types["ListItem"]
+
     lines: list[str] = []
     slug = output_path.stem
     prefix_base = f"https://wordlift.io/shacl/google/{slug}/"
@@ -181,27 +185,67 @@ def _write_feature(feature: FeatureData, output_path: Path, overwrite: bool) ->
     lines.append("@prefix schema: <http://schema.org/> .")
     lines.append("")
     lines.append(f"# Source: {feature.url}")
-    lines.append(f"# Generated: {datetime.utcnow().isoformat(timespec='seconds')}Z")
+    lines.append(
+        f"# Generated: {datetime.now(timezone.utc).isoformat(timespec='seconds')}Z"
+    )
     lines.append(
         "# Notes: required properties => errors; recommended properties => warnings."
     )
     lines.append("")
 
     for type_name in sorted(feature.types.keys()):
+        if scoped_list_item and type_name == "ListItem":
+            continue
         bucket = feature.types[type_name]
         shape_name = f":google_{type_name}Shape"
         lines.append(shape_name)
         lines.append("  a sh:NodeShape ;")
         lines.append(f"  sh:targetClass schema:{type_name} ;")
 
         for prop in sorted(bucket["required"]):
+            if (
+                scoped_list_item
+                and type_name == "ItemList"
+                and prop == "itemListElement"
+            ):
+                lines.append("  sh:property [")
+                lines.append("    sh:path schema:itemListElement ;")
+                lines.append("    sh:minCount 1 ;")
+                lines.append("    sh:node [")
+                lines.append("      a sh:NodeShape ;")
+                lines.append("      sh:class schema:ListItem ;")
+                for item_prop in sorted(scoped_list_item["required"]):
+                    item_path = _prop_path(item_prop)
+                    lines.append("      sh:property [")
+                    lines.append(f"        sh:path {item_path} ;")
+                    lines.append("        sh:minCount 1 ;")
+                    lines.append("      ] ;")
+                for item_prop in sorted(scoped_list_item["recommended"]):
+                    item_path = _prop_path(item_prop)
+                    lines.append("      sh:property [")
+                    lines.append(f"        sh:path {item_path} ;")
+                    lines.append("        sh:minCount 1 ;")
+                    lines.append("        sh:severity sh:Warning ;")
+                    lines.append(
+                        f'        sh:message "Recommended by Google: {item_prop}." ;'
+                    )
+                    lines.append("      ] ;")
+                lines.append("    ] ;")
+                lines.append("  ] ;")
+                continue
             path = _prop_path(prop)
             lines.append("  sh:property [")
             lines.append(f"    sh:path {path} ;")
             lines.append("    sh:minCount 1 ;")
             lines.append("  ] ;")
 
         for prop in sorted(bucket["recommended"]):
+            if (
+                scoped_list_item
+                and type_name == "ItemList"
+                and prop == "itemListElement"
+            ):
+                continue
             path = _prop_path(prop)
             lines.append("  sh:property [")
             lines.append(f"    sh:path {path} ;")
@@ -381,7 +425,9 @@ def generate_schema_shacls(output_file: Path, overwrite: bool) -> int:
     lines.append(f"@prefix schema: <{SCHEMA_DATA}> .")
     lines.append("")
     lines.append(f"# Source: {SCHEMA_JSONLD_URL}")
-    lines.append(f"# Generated: {datetime.utcnow().isoformat(timespec='seconds')}Z")
+    lines.append(
+        f"# Generated: {datetime.now(timezone.utc).isoformat(timespec='seconds')}Z"
+    )
     lines.append(
         "# Notes: schema.org grammar checks only; all constraints are warnings."
     )

wordlift_sdk/validation/shacls/google-carousel.ttl

@@ -3,7 +3,7 @@
 @prefix schema: <http://schema.org/> .
 
 # Source: https://developers.google.com/search/docs/appearance/structured-data/carousel
-# Generated: 2026-01-13T11:23:16Z
+# Generated: 2026-02-04T18:12:24+00:00Z
 # Notes: required properties => errors; recommended properties => warnings.
 
 :google_ItemListShape
@@ -12,26 +12,29 @@
   sh:property [
     sh:path schema:itemListElement ;
     sh:minCount 1 ;
-  ] ;
-.
-
-:google_ListItemShape
-  a sh:NodeShape ;
-  sh:targetClass schema:ListItem ;
-  sh:property [
-    sh:path schema:item ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:name ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:position ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:url ;
-    sh:minCount 1 ;
+    sh:node [
+      a sh:NodeShape ;
+      sh:class schema:ListItem ;
+      sh:property [
+        sh:path schema:item ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path ( schema:item schema:name ) ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path ( schema:item schema:url ) ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path schema:position ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path schema:url ;
+        sh:minCount 1 ;
+      ] ;
+    ] ;
   ] ;
 .