[IMP] website, *: introduce JsonLd builder and structured data

*=website_blog

Body:
This commit introduces a reusable JsonLd builder for Schema.org
payloads and integrates structured data generation in website and
website_blog.

- add a JsonLd helper with snake_case to camelCase normalization,
  nested schema support, datetime normalization, and safe rendering for
  single or multiple schemas
- add website structured data foundations (organization schema default
  and breadcrumb helper) through a dedicated mixin
- expose website-level structured data generation and inject
  structured_data in template rendering context
- render JSON-LD payload in website layout head
- add images_from_html utility to collect post images from blog content
- generate blog schemas for listing and detail pages (Blog,
  CollectionPage, BlogPosting, BreadcrumbList)
- pass structured_data from blog controllers for both list and detail
  routes
- add dedicated tests validating JsonLd behavior and serialization rules

This change enables consistent, extensible structured-data generation
across website and blog pages.

task-4655276

Author: gppa-odoo

addons/website/helpers/__init__.py

@@ -0,0 +1,3 @@
+# Part of Odoo. See LICENSE file for full copyright and licensing details.
+
+from . import jsonld_builder

addons/website/helpers/jsonld_builder.py

@@ -0,0 +1,233 @@
+# Part of Odoo. See LICENSE file for full copyright and licensing details.
+
+from __future__ import annotations
+
+from datetime import UTC
+from typing import Any
+
+from odoo import fields
+from odoo.tools.json import scriptsafe
+
+
+class JsonLd:
+    """
+    Fluent builder for creating Schema.org JSON-LD structured data.
+
+    Example:
+        >>> product = JsonLd("Product", {
+        ...     "name": "Laptop",
+        ...     "sku": "LAP-001",
+        ...     "price": 999.99,
+        ... })
+        >>> offer = JsonLd("Offer", {
+        ...     "price": 999.99,
+        ...     "priceCurrency": "USD",
+        ...     "availability": "https://schema.org/InStock"
+        ... })
+        >>> product.add_nested({"offers": offer})
+
+        >>> JsonLd.render_structured_data([product])
+    """
+    __slots__ = ("schema_type", "values")
+
+    def __init__(self, schema_type: str, /, values: dict[str, Any] | None = None):
+        self.schema_type = schema_type
+        self.values = {}
+        if values:
+            self.set(values)
+
+    @staticmethod
+    def _has_invalid_types(values, expected_type: type) -> list[str]:
+        """Return class names of items that are not instances of *expected_type*,
+        in the order they first appear."""
+        return list(dict.fromkeys(
+            v.__class__.__name__
+            for v in values
+            if v is not None and not isinstance(v, expected_type)
+        ))
+
+    @staticmethod
+    def render_structured_data(builders: list[JsonLd]) -> str | bool:
+        """Render a list of JsonLd builders into a JSON-LD string.
+        Falsy values (e.g., None) are ignored. If no valid builders remain,
+        returns False.
+        Args:
+            builders: A list of JsonLd instances.
+        Returns:
+            A JSON string containing the rendered JSON-LD data, or False if
+            the list is empty or contains no valid builders.
+        Raises:
+            TypeError: If any item in *builders* is not a JsonLd instance.
+        Example:
+            >>> org = JsonLd("Organization", {"name": "Example Corp"})
+            >>> website = JsonLd("WebSite", {"name": "Example Site", "url": "https://example.com"})
+            >>> JsonLd.render_structured_data([org, website])
+            >>> Output: [
+                {
+                    "@type": "Organization",
+                    "@context": "https://schema.org",
+                    "name": "Example Corp"
+                },
+                {
+                    "@type": "WebSite",
+                    "@context": "https://schema.org",
+                    "name": "Example Site",
+                    "url": "https://example.com"
+                }
+            ]
+        """
+        if not builders:
+            return False
+        invalid = JsonLd._has_invalid_types(builders, JsonLd)
+        if invalid:
+            raise TypeError(
+                f"render_structured_data() expects JsonLd instances, "
+                f"got: {', '.join(invalid)}",
+            )
+        rendered = [b._to_jsonld_dict() for b in builders if b]
+        if not rendered:
+            return False
+        return scriptsafe.dumps(rendered, ensure_ascii=False)
+
+    @staticmethod
+    def to_iso_datetime(dt) -> str | None:
+        """Convert datetime to ISO-8601 string with timezone information.
+        As per https://schema.org/DateTime, the value must be in ISO-8601 format
+        and include timezone information.
+        Args:
+            dt: Datetime object or compatible value
+        Returns:
+            ISO-8601 formatted string with timezone, or None if dt is falsy
+            or cannot be converted.
+        Example:
+            >>> from datetime import datetime
+            >>> dt = datetime(2025, 1, 15, 10, 30)
+            >>> JsonLd.to_iso_datetime(dt)
+            '2025-01-15T10:30:00+00:00'
+        """
+        as_datetime = fields.Datetime.to_datetime(dt)
+        if not as_datetime:
+            return None
+        if not as_datetime.tzinfo:
+            as_datetime = as_datetime.replace(tzinfo=UTC)
+        return as_datetime.isoformat()
+
+    def get(self, key: str, default=None):
+        """Retrieve a stored value by key.
+        Args:
+            key: Property name
+            default: Value returned when the key is absent.
+        Returns:
+            The stored value, or *default*.
+        """
+        return self.values.get(key, default)
+
+    def set(self, values: dict[str, Any]) -> JsonLd:
+        """Set properties on the schema (overwrites existing keys).
+        Properties are automatically converted from snake_case to camelCase.
+        Args:
+            values: Property name-value pairs
+        Returns:
+            Self for method chaining
+        Example:
+            >>> product = JsonLd("Product")
+            >>> product.set({"name": "Widget", "price": 29.99, "brand": "BrandName"})
+        """
+        for key, value in values.items():
+            if value is None:
+                continue
+            items = value if isinstance(value, list) else [value]
+            if any(isinstance(v, JsonLd) for v in items):
+                raise TypeError(f"Key '{key}' contains JsonLd value(s). Use add_nested() instead.")
+            self.values[key] = value
+        return self
+
+    def add_nested(self, values: dict[str, JsonLd | list[JsonLd] | None]) -> JsonLd:
+        """Add nested schema builder(s).
+        A single nested value is stored as-is; values are converted to a list
+        only when multiple nested values exist for the same key. None values
+        are ignored.
+        Args:
+            values: Property name to JsonLd (or list of them) mapping
+        Returns:
+            Self for method chaining
+        Example:
+            >>> product = JsonLd("Product", {"name": "Widget"})
+            >>> offer = JsonLd("Offer", {"price": 99.99, "priceCurrency": "USD"})
+            >>> product.add_nested({"offers": offer})
+            >>> isinstance(product.get("offers"), JsonLd)
+            True
+            >>>
+            >>> # Adding another nested item appends to the existing value
+            >>> offer2 = JsonLd("Offer", {"price": 79.99, "priceCurrency": "EUR"})
+            >>> product.add_nested({"offers": offer2})  # offers is now [offer, offer2]
+            >>>
+            >>> # Multiple nested items at once
+            >>> product.add_nested({"offers": [offer1, offer2, offer3]})
+        """
+        for key, builder in values.items():
+            if builder is None:
+                continue
+            items = builder if isinstance(builder, list) else [builder]
+            if not items:
+                continue
+            invalid = self._has_invalid_types(items, JsonLd)
+            if invalid:
+                raise TypeError(
+                    f"add_nested() expects JsonLd instances for key '{key}', "
+                    f"got: {', '.join(invalid)}")
+            existing = self.values.get(key)
+            if existing is None:
+                self.values[key] = items[0] if len(items) == 1 else items
+            elif isinstance(existing, JsonLd):
+                self.values[key] = [existing, *items]
+            elif isinstance(existing, list):
+                is_jsonld_list = isinstance(existing[0], JsonLd)
+                if not is_jsonld_list:
+                    raise TypeError(f"Cannot append to '{key}', existing value is not a list of JsonLd")
+                existing.extend(items)
+            else:
+                raise TypeError(f"Cannot append to '{key}', existing type: {existing.__class__.__name__}")
+        return self
+
+    def _to_jsonld_dict(self, include_context: bool = True) -> dict[str, Any]:
+        """Convert this builder to a JSON-LD dictionary.
+        Args:
+            include_context: Whether to include @context
+        Returns:
+            JSON-LD dictionary
+        """
+        normalized_values = {}
+        for key, value in self.values.items():
+            v = self._normalize_value(value)
+            if v is not None:
+                normalized_values[key] = v
+        # Only @id -> reference object
+        if len(normalized_values) == 1 and "@id" in normalized_values:
+            return normalized_values
+        data: dict[str, Any] = {}
+        if include_context:
+            data["@context"] = "https://schema.org"
+        data["@type"] = self.schema_type
+        data.update(normalized_values)
+        return data
+
+    def _normalize_value(self, value):
+        """Normalize a value for JSON-LD rendering."""
+        # False is also treated as value. None and empty lists are ignored.
+        if value is None:
+            return None
+        if isinstance(value, JsonLd):
+            return value._to_jsonld_dict(include_context=False)
+        if isinstance(value, list):
+            normalized = [
+                self._normalize_value(v)
+                for v in value
+                if v is not None
+            ]
+            if not normalized:
+                return None
+            # Single item arrays can be unwrapped as per Schema.org spec:
+            # a property with one value doesn't need to be wrapped in an array.
+            return normalized if len(normalized) > 1 else normalized[0]
+        return value

addons/website/models/mixins.py

@@ -6,6 +6,7 @@
 from odoo import api, fields, models, _
 from odoo.fields import Domain
 from odoo.addons.website.tools import text_from_html
+from odoo.addons.website.helpers.jsonld_builder import JsonLd
 from odoo.http import request
 from odoo.exceptions import AccessError, UserError
 from odoo.models import Query
@@ -870,3 +871,48 @@ def _search_highlight_tags(self, field_meta, value, term):
             return False, value, 'html'
 
         return True, value, 'tags'
+
+
+class WebsiteStructuredDataMixin(models.AbstractModel):
+    _name = 'website.structured_data.mixin'
+    _description = 'Website Structured Data Mixin'
+
+    def get_json_ld(self, is_detail_page=False):
+        """Return the JSON-LD structured data for this record.
+        :param is_detail_page: whether the structured data is for a detail page
+        :return: string containing the JSON-LD structured data
+        :rtype: str (JSON-LD)
+        """
+        return JsonLd.render_structured_data(self._build_structured_data(is_detail_page=is_detail_page))
+
+    def _build_structured_data(self, is_detail_page=False):
+        """Return a list of JsonLd builders for this record.
+
+        Default implementation returns the Organization schema of the
+        current website.  Override in sub-models to append page-specific
+        schemas (BlogPosting, Product, BreadcrumbList, ...).
+
+        :param is_detail_page: whether the structured data is for a detail page
+        :return: list of JsonLd builders to be rendered in the page
+        :rtype: list[JsonLd]
+        """
+        website = self.env['website'].get_current_website()
+        return [website.organization_structured_data()]
+
+    def _build_breadcrumb_schema(self, items):
+        """Generic breadcrumb builder.
+
+        :param items: List of ``(name, url)`` tuples.
+        :return: BreadcrumbList schema, or ``None`` when no valid items.
+        :rtype: JsonLd | None
+        """
+        valid_items = [item for item in items if item is not None]
+        if not valid_items:
+            return None
+        list_items = []
+        for position, (name, url) in enumerate(valid_items, start=1):
+            item = JsonLd("ListItem", {"position": position, "name": name, "item": url})
+            list_items.append(item)
+        breadcrumbs = JsonLd("BreadcrumbList")
+        breadcrumbs.add_nested({"itemListElement": list_items})
+        return breadcrumbs

addons/website/models/website.py

@@ -18,6 +18,7 @@
 from urllib.parse import urlparse, urlsplit
 from werkzeug import urls
 
+from odoo.addons.website.helpers.jsonld_builder import JsonLd
 from odoo import api, fields, models, tools, release
 from odoo.addons.website.models.ir_http import sitemap_qs2dom
 from odoo.addons.website.tools import similarity_score, text_from_html, get_base_domain
@@ -2491,3 +2492,21 @@ def _is_tag_domains_watchlisted(self, tagName, atts):
 
     def _is_tag_classes_watchlisted(self, tagName, atts):
         return self._get_blocked_iframe_containers_classes().intersection((atts.get('class') or '').split(' '))
+
+    def get_json_ld(self):
+        """Generate structured data for the website."""
+        self.ensure_one()
+        return JsonLd.render_structured_data([self.organization_structured_data()])
+
+    def organization_structured_data(self):
+        """Generate Organization structured data using only website context."""
+        self.ensure_one()
+        base_url = self.get_base_url()
+        logo_url = f"{base_url}/logo.png?company={self.company_id.id}"
+        return JsonLd("Organization",
+            {
+                "name": self.name,
+                "url": base_url,
+                "@id": f"{base_url}/#organization",
+            },
+        ).add_nested({"logo": JsonLd("ImageObject", {"url": logo_url})})

addons/website/tests/__init__.py

@@ -19,6 +19,7 @@
 from . import test_iap
 from . import test_import_files
 from . import test_ir_asset
+from . import test_jsonld_builder
 from . import test_lang_url
 from . import test_menu
 from . import test_multi_website