wordlift-sdk 2.10.3__tar.gz → 2.12.0__tar.gz

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wordlift-sdk
-Version: 2.10.3
+Version: 2.12.0
 Summary: 
 Author: David Riccitelli
 Author-email: david@wordlift.io
@@ -118,6 +118,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. When a feature includes both container types (for example `ItemList`, `BreadcrumbList`, `QAPage`, `FAQPage`, `Quiz`, `ProfilePage`, `Product`, `Recipe`, `Course`) and their contained types (`ListItem`, `Question`, `Answer`, `Comment`, `Offer`, `HowToStep`, `Person`, `Organization`), the generator scopes the contained constraints under the container properties to avoid enforcing them on unrelated nodes.
+
 ## Testing
 
 ```bash
@@ -129,4 +133,3 @@ poetry run pytest
 
 - [Google Sheets Lookup](docs/google_sheets_lookup.md): Utility for O(1) lookups from Google Sheets.
 
-

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/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. When a feature includes both container types (for example `ItemList`, `BreadcrumbList`, `QAPage`, `FAQPage`, `Quiz`, `ProfilePage`, `Product`, `Recipe`, `Course`) and their contained types (`ListItem`, `Question`, `Answer`, `Comment`, `Offer`, `HowToStep`, `Person`, `Organization`), the generator scopes the contained constraints under the container properties to avoid enforcing them on unrelated nodes.
+
 ## 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.
-

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/pyproject.toml

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

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/wordlift_sdk/validation/generator.py

@@ -6,7 +6,7 @@ import argparse
 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
 
@@ -169,10 +169,136 @@ def _prop_path(prop: str) -> str:
     return f"( {seq} )"
 
 
+_SCOPED_CHILD_RULES: dict[str, dict[str, list[str]]] = {
+    "ItemList": {"itemListElement": ["ListItem"]},
+    "BreadcrumbList": {"itemListElement": ["ListItem"]},
+    "QAPage": {"mainEntity": ["Question"]},
+    "FAQPage": {"mainEntity": ["Question"]},
+    "Quiz": {"hasPart": ["Question"]},
+    "ProfilePage": {"mainEntity": ["Person", "Organization"]},
+    "Question": {
+        "acceptedAnswer": ["Answer"],
+        "suggestedAnswer": ["Answer"],
+        "comment": ["Comment"],
+    },
+    "Answer": {"comment": ["Comment"]},
+    "Product": {"offers": ["Offer"]},
+    "Recipe": {"recipeInstructions": ["HowToStep"], "step": ["HowToStep"]},
+    "Course": {"provider": ["Organization"], "hasPart": ["Course", "CreativeWork"]},
+}
+
+
+def _emit_property(
+    lines: list[str],
+    prop: str,
+    required: bool,
+    child_types: list[str] | None,
+    indent: int,
+    buckets: dict[str, dict[str, set[str]]],
+    visited: set[str],
+) -> None:
+    sp = " " * indent
+    path = _prop_path(prop)
+    lines.append(f"{sp}sh:property [")
+    lines.append(f"{sp}  sh:path {path} ;")
+    lines.append(f"{sp}  sh:minCount 1 ;")
+    if not required:
+        lines.append(f"{sp}  sh:severity sh:Warning ;")
+        lines.append(f'{sp}  sh:message "Recommended by Google: {prop}." ;')
+    if child_types:
+        valid_children = [
+            child_type
+            for child_type in child_types
+            if child_type not in visited and child_type in buckets
+        ]
+        if len(valid_children) == 1:
+            child_type = valid_children[0]
+            child_bucket = buckets.get(child_type)
+            node_indent = indent + 2
+            node_sp = " " * node_indent
+            lines.append(f"{node_sp}sh:node [")
+            _emit_node(
+                lines,
+                child_type,
+                child_bucket,
+                node_indent + 2,
+                buckets,
+                visited | {child_type},
+            )
+            lines.append(f"{node_sp}] ;")
+        elif len(valid_children) > 1:
+            or_indent = indent + 2
+            or_sp = " " * or_indent
+            lines.append(f"{or_sp}sh:or (")
+            for child_type in valid_children:
+                child_bucket = buckets.get(child_type)
+                lines.append(f"{or_sp}  [")
+                _emit_node(
+                    lines,
+                    child_type,
+                    child_bucket,
+                    or_indent + 4,
+                    buckets,
+                    visited | {child_type},
+                )
+                lines.append(f"{or_sp}  ]")
+            lines.append(f"{or_sp}) ;")
+    lines.append(f"{sp}] ;")
+
+
+def _emit_node(
+    lines: list[str],
+    type_name: str,
+    bucket: dict[str, set[str]],
+    indent: int,
+    buckets: dict[str, dict[str, set[str]]],
+    visited: set[str],
+) -> None:
+    sp = " " * indent
+    lines.append(f"{sp}a sh:NodeShape ;")
+    lines.append(f"{sp}sh:class schema:{type_name} ;")
+
+    child_rules = _SCOPED_CHILD_RULES.get(type_name, {})
+    for prop in sorted(bucket["required"]):
+        child_types = child_rules.get(prop)
+        _emit_property(
+            lines,
+            prop,
+            required=True,
+            child_types=child_types,
+            indent=indent,
+            buckets=buckets,
+            visited=visited,
+        )
+
+    for prop in sorted(bucket["recommended"]):
+        child_types = child_rules.get(prop)
+        _emit_property(
+            lines,
+            prop,
+            required=False,
+            child_types=child_types,
+            indent=indent,
+            buckets=buckets,
+            visited=visited,
+        )
+
+
 def _write_feature(feature: FeatureData, output_path: Path, overwrite: bool) -> bool:
     if output_path.exists() and not overwrite:
         return False
 
+    scoped_types: set[str] = set()
+    for parent_type, rules in _SCOPED_CHILD_RULES.items():
+        if parent_type not in feature.types:
+            continue
+        for child_types in rules.values():
+            for child_type in child_types:
+                if child_type == parent_type:
+                    continue
+                if child_type in feature.types:
+                    scoped_types.add(child_type)
+
     lines: list[str] = []
     slug = output_path.stem
     prefix_base = f"https://wordlift.io/shacl/google/{slug}/"
@@ -181,13 +307,18 @@ 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(
+        "# Generated: "
+        f"{datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z')}"
+    )
     lines.append(
         "# Notes: required properties => errors; recommended properties => warnings."
     )
     lines.append("")
 
     for type_name in sorted(feature.types.keys()):
+        if type_name in scoped_types:
+            continue
         bucket = feature.types[type_name]
         shape_name = f":google_{type_name}Shape"
         lines.append(shape_name)
@@ -195,20 +326,28 @@ def _write_feature(feature: FeatureData, output_path: Path, overwrite: bool) ->
         lines.append(f"  sh:targetClass schema:{type_name} ;")
 
         for prop in sorted(bucket["required"]):
-            path = _prop_path(prop)
-            lines.append("  sh:property [")
-            lines.append(f"    sh:path {path} ;")
-            lines.append("    sh:minCount 1 ;")
-            lines.append("  ] ;")
+            child_types = _SCOPED_CHILD_RULES.get(type_name, {}).get(prop)
+            _emit_property(
+                lines,
+                prop,
+                required=True,
+                child_types=child_types,
+                indent=2,
+                buckets=feature.types,
+                visited={type_name},
+            )
 
         for prop in sorted(bucket["recommended"]):
-            path = _prop_path(prop)
-            lines.append("  sh:property [")
-            lines.append(f"    sh:path {path} ;")
-            lines.append("    sh:minCount 1 ;")
-            lines.append("    sh:severity sh:Warning ;")
-            lines.append(f'    sh:message "Recommended by Google: {prop}." ;')
-            lines.append("  ] ;")
+            child_types = _SCOPED_CHILD_RULES.get(type_name, {}).get(prop)
+            _emit_property(
+                lines,
+                prop,
+                required=False,
+                child_types=child_types,
+                indent=2,
+                buckets=feature.types,
+                visited={type_name},
+            )
 
         lines.append(".")
         lines.append("")
@@ -381,7 +520,10 @@ 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(
+        "# Generated: "
+        f"{datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z')}"
+    )
     lines.append(
         "# Notes: schema.org grammar checks only; all constraints are warnings."
     )

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/wordlift_sdk/validation/shacls/google-breadcrumb.ttl

@@ -3,7 +3,7 @@
 @prefix schema: <http://schema.org/> .
 
 # Source: https://developers.google.com/search/docs/appearance/structured-data/breadcrumb
-# Generated: 2026-01-13T11:23:15Z
+# Generated: 2026-02-04T20:00:50Z
 # Notes: required properties => errors; recommended properties => warnings.
 
 :google_BreadcrumbListShape
@@ -12,22 +12,21 @@
   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:node [
+      a sh:NodeShape ;
+      sh:class 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 ;
+      ] ;
+    ] ;
   ] ;
 .

wordlift_sdk-2.12.0/wordlift_sdk/validation/shacls/google-carousel.ttl

@@ -0,0 +1,40 @@
+@prefix : <https://wordlift.io/shacl/google/google-carousel/> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix schema: <http://schema.org/> .
+
+# Source: https://developers.google.com/search/docs/appearance/structured-data/carousel
+# Generated: 2026-02-04T20:00:51Z
+# Notes: required properties => errors; recommended properties => warnings.
+
+:google_ItemListShape
+  a sh:NodeShape ;
+  sh:targetClass schema:ItemList ;
+  sh:property [
+    sh:path schema:itemListElement ;
+    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 ;
+      ] ;
+    ] ;
+  ] ;
+.

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/wordlift_sdk/validation/shacls/google-course.ttl

@@ -3,7 +3,7 @@
 @prefix schema: <http://schema.org/> .
 
 # Source: https://developers.google.com/search/docs/appearance/structured-data/course
-# Generated: 2026-01-13T11:23:18Z
+# Generated: 2026-02-04T20:09:17Z
 # Notes: required properties => errors; recommended properties => warnings.
 
 :google_CourseShape
@@ -29,15 +29,15 @@
   a sh:NodeShape ;
   sh:targetClass schema:ItemList ;
   sh:property [
-    sh:path schema:itemListElement ;
+    sh:path ( schema:ListItem schema:position ) ;
     sh:minCount 1 ;
   ] ;
   sh:property [
-    sh:path schema:position ;
+    sh:path ( schema:ListItem schema:url ) ;
     sh:minCount 1 ;
   ] ;
   sh:property [
-    sh:path schema:url ;
+    sh:path schema:itemListElement ;
     sh:minCount 1 ;
   ] ;
 .

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/wordlift_sdk/validation/shacls/google-education-qa.ttl

@@ -3,26 +3,9 @@
 @prefix schema: <http://schema.org/> .
 
 # Source: https://developers.google.com/search/docs/appearance/structured-data/education-qa
-# Generated: 2026-01-13T11:23:22Z
+# Generated: 2026-02-04T20:00:52Z
 # Notes: required properties => errors; recommended properties => warnings.
 
-:google_QuestionShape
-  a sh:NodeShape ;
-  sh:targetClass schema:Question ;
-  sh:property [
-    sh:path schema:acceptedAnswer ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:eduQuestionType ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:text ;
-    sh:minCount 1 ;
-  ] ;
-.
-
 :google_QuizShape
   a sh:NodeShape ;
   sh:targetClass schema:Quiz ;
@@ -37,6 +20,22 @@
   sh:property [
     sh:path schema:hasPart ;
     sh:minCount 1 ;
+    sh:node [
+      a sh:NodeShape ;
+      sh:class schema:Question ;
+      sh:property [
+        sh:path schema:acceptedAnswer ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path schema:eduQuestionType ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path schema:text ;
+        sh:minCount 1 ;
+      ] ;
+    ] ;
   ] ;
   sh:property [
     sh:path schema:text ;
@@ -49,10 +48,10 @@
     sh:message "Recommended by Google: about." ;
   ] ;
   sh:property [
-    sh:path schema:alignmentType ;
+    sh:path ( schema:about schema:name ) ;
     sh:minCount 1 ;
     sh:severity sh:Warning ;
-    sh:message "Recommended by Google: alignmentType." ;
+    sh:message "Recommended by Google: about.name." ;
   ] ;
   sh:property [
     sh:path schema:educationalAlignment ;
@@ -61,15 +60,15 @@
     sh:message "Recommended by Google: educationalAlignment." ;
   ] ;
   sh:property [
-    sh:path schema:name ;
+    sh:path ( schema:educationalAlignment schema:alignmentType ) ;
     sh:minCount 1 ;
     sh:severity sh:Warning ;
-    sh:message "Recommended by Google: name." ;
+    sh:message "Recommended by Google: educationalAlignment.alignmentType." ;
   ] ;
   sh:property [
-    sh:path schema:targetName ;
+    sh:path ( schema:educationalAlignment schema:targetName ) ;
     sh:minCount 1 ;
     sh:severity sh:Warning ;
-    sh:message "Recommended by Google: targetName." ;
+    sh:message "Recommended by Google: educationalAlignment.targetName." ;
   ] ;
 .

wordlift_sdk-2.12.0/wordlift_sdk/validation/shacls/google-faqpage.ttl

@@ -0,0 +1,36 @@
+@prefix : <https://wordlift.io/shacl/google/google-faqpage/> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix schema: <http://schema.org/> .
+
+# Source: https://developers.google.com/search/docs/appearance/structured-data/faqpage
+# Generated: 2026-02-04T20:00:53Z
+# Notes: required properties => errors; recommended properties => warnings.
+
+:google_FAQPageShape
+  a sh:NodeShape ;
+  sh:targetClass schema:FAQPage ;
+  sh:property [
+    sh:path schema:mainEntity ;
+    sh:minCount 1 ;
+    sh:node [
+      a sh:NodeShape ;
+      sh:class schema:Question ;
+      sh:property [
+        sh:path schema:acceptedAnswer ;
+        sh:minCount 1 ;
+        sh:node [
+          a sh:NodeShape ;
+          sh:class schema:Answer ;
+          sh:property [
+            sh:path schema:text ;
+            sh:minCount 1 ;
+          ] ;
+        ] ;
+      ] ;
+      sh:property [
+        sh:path schema:name ;
+        sh:minCount 1 ;
+      ] ;
+    ] ;
+  ] ;
+.

{wordlift_sdk-2.10.3 → wordlift_sdk-2.12.0}/wordlift_sdk/validation/shacls/google-merchant-listing.ttl

@@ -3,18 +3,18 @@
 @prefix schema: <http://schema.org/> .
 
 # Source: https://developers.google.com/search/docs/appearance/structured-data/merchant-listing
-# Generated: 2026-01-13T11:23:41Z
+# Generated: 2026-02-04T20:09:18Z
 # Notes: required properties => errors; recommended properties => warnings.
 
 :google_3DModelShape
   a sh:NodeShape ;
   sh:targetClass schema:3DModel ;
   sh:property [
-    sh:path schema:contentUrl ;
+    sh:path schema:encoding ;
     sh:minCount 1 ;
   ] ;
   sh:property [
-    sh:path schema:encoding ;
+    sh:path ( schema:encoding schema:contentUrl ) ;
     sh:minCount 1 ;
   ] ;
 .
@@ -40,53 +40,6 @@
   ] ;
 .
 
-:google_OfferShape
-  a sh:NodeShape ;
-  sh:targetClass schema:Offer ;
-  sh:property [
-    sh:path schema:price ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:priceCurrency ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:priceSpecification ;
-    sh:minCount 1 ;
-  ] ;
-  sh:property [
-    sh:path schema:availability ;
-    sh:minCount 1 ;
-    sh:severity sh:Warning ;
-    sh:message "Recommended by Google: availability." ;
-  ] ;
-  sh:property [
-    sh:path schema:hasMerchantReturnPolicy ;
-    sh:minCount 1 ;
-    sh:severity sh:Warning ;
-    sh:message "Recommended by Google: hasMerchantReturnPolicy." ;
-  ] ;
-  sh:property [
-    sh:path schema:itemCondition ;
-    sh:minCount 1 ;
-    sh:severity sh:Warning ;
-    sh:message "Recommended by Google: itemCondition." ;
-  ] ;
-  sh:property [
-    sh:path schema:shippingDetails ;
-    sh:minCount 1 ;
-    sh:severity sh:Warning ;
-    sh:message "Recommended by Google: shippingDetails." ;
-  ] ;
-  sh:property [
-    sh:path schema:url ;
-    sh:minCount 1 ;
-    sh:severity sh:Warning ;
-    sh:message "Recommended by Google: url." ;
-  ] ;
-.
-
 :google_OfferShippingDetailsShape
   a sh:NodeShape ;
   sh:targetClass schema:OfferShippingDetails ;
@@ -94,10 +47,6 @@
     sh:path schema:addressCountry ;
     sh:minCount 1 ;
   ] ;
-  sh:property [
-    sh:path schema:currency ;
-    sh:minCount 1 ;
-  ] ;
   sh:property [
     sh:path schema:deliveryTime ;
     sh:minCount 1 ;
@@ -111,7 +60,11 @@
     sh:minCount 1 ;
   ] ;
   sh:property [
-    sh:path schema:value ;
+    sh:path ( schema:shippingRate schema:currency ) ;
+    sh:minCount 1 ;
+  ] ;
+  sh:property [
+    sh:path ( schema:shippingRate schema:value ) ;
     sh:minCount 1 ;
   ] ;
   sh:property [
@@ -165,6 +118,52 @@
   sh:property [
     sh:path schema:offers ;
     sh:minCount 1 ;
+    sh:node [
+      a sh:NodeShape ;
+      sh:class schema:Offer ;
+      sh:property [
+        sh:path schema:price ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path schema:priceCurrency ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path schema:priceSpecification ;
+        sh:minCount 1 ;
+      ] ;
+      sh:property [
+        sh:path schema:availability ;
+        sh:minCount 1 ;
+        sh:severity sh:Warning ;
+        sh:message "Recommended by Google: availability." ;
+      ] ;
+      sh:property [
+        sh:path schema:hasMerchantReturnPolicy ;
+        sh:minCount 1 ;
+        sh:severity sh:Warning ;
+        sh:message "Recommended by Google: hasMerchantReturnPolicy." ;
+      ] ;
+      sh:property [
+        sh:path schema:itemCondition ;
+        sh:minCount 1 ;
+        sh:severity sh:Warning ;
+        sh:message "Recommended by Google: itemCondition." ;
+      ] ;
+      sh:property [
+        sh:path schema:shippingDetails ;
+        sh:minCount 1 ;
+        sh:severity sh:Warning ;
+        sh:message "Recommended by Google: shippingDetails." ;
+      ] ;
+      sh:property [
+        sh:path schema:url ;
+        sh:minCount 1 ;
+        sh:severity sh:Warning ;
+        sh:message "Recommended by Google: url." ;
+      ] ;
+    ] ;
   ] ;
   sh:property [
     sh:path schema:aggregateRating ;
@@ -179,10 +178,10 @@
     sh:message "Recommended by Google: audience." ;
   ] ;
   sh:property [
-    sh:path schema:brand ;
+    sh:path ( schema:brand schema:name ) ;
     sh:minCount 1 ;
     sh:severity sh:Warning ;
-    sh:message "Recommended by Google: brand." ;
+    sh:message "Recommended by Google: brand.name." ;
   ] ;
   sh:property [
     sh:path schema:color ;