feat(codegen): generate pages and links for Pydantic built-in types

Pydantic types like HttpUrl and EmailStr appear in field annotations
but previously rendered as unlinked inline code. Each referenced
Pydantic type now gets its own page under pydantic/<module>/ with a
description, upstream Pydantic docs link, and Used By section.

Discovery is reference-driven: the type collection visitor detects
PRIMITIVE-kind types from pydantic modules in expanded feature trees.
PydanticTypeSpec joins the SupplementarySpec union and flows through
placement, reverse references, and rendering.

Linking is registry-driven for all PRIMITIVE-kind types. Any primitive
with a page in the placement registry gets linked, whether it's a
Pydantic type (individual page) or a registered numeric primitive
(aggregate page). This also links int32/float64 to the primitives
page, which they weren't before.

Shared is_pydantic_sourced() predicate gates collection and reverse
reference tracking to pydantic-origin types without restricting the
linking mechanism.

Author: mojodna

packages/overture-schema-codegen/src/overture/schema/codegen/markdown_pipeline.py

@@ -21,6 +21,7 @@
     render_geometry_from_values,
     render_newtype,
     render_primitives_from_specs,
+    render_pydantic_type,
 )
 from .model_extraction import expand_model_tree
 from .path_assignment import (
@@ -39,6 +40,7 @@
     FeatureSpec,
     ModelSpec,
     NewTypeSpec,
+    PydanticTypeSpec,
     SupplementarySpec,
     TypeIdentity,
     UnionSpec,
@@ -88,7 +90,7 @@ def _render_supplement(
     registry: dict[TypeIdentity, PurePosixPath],
     reverse_refs: dict[TypeIdentity, list[UsedByEntry]],
 ) -> RenderedPage:
-    """Render a single supplementary page (enum, NewType, or sub-model)."""
+    """Render a single supplementary type page."""
     output_path = resolve_output_path(tid, registry)
     ctx = LinkContext(output_path, registry)
     used_by = reverse_refs.get(tid)
@@ -99,6 +101,8 @@ def _render_supplement(
         content = render_newtype(spec, ctx, used_by=used_by)
     elif isinstance(spec, ModelSpec):
         content = render_feature(spec, ctx, used_by=used_by)
+    elif isinstance(spec, PydanticTypeSpec):
+        content = render_pydantic_type(spec, link_ctx=ctx, used_by=used_by)
     else:
         raise TypeError(f"Unhandled SupplementarySpec variant: {type(spec).__name__}")
 

packages/overture-schema-codegen/src/overture/schema/codegen/markdown_renderer.py

@@ -29,6 +29,7 @@
     ModelSpec,
     NewTypeSpec,
     PrimitiveSpec,
+    PydanticTypeSpec,
     TypeIdentity,
     UnionSpec,
 )
@@ -42,6 +43,7 @@
     "render_geometry_from_values",
     "render_newtype",
     "render_primitives_from_specs",
+    "render_pydantic_type",
 ]
 
 
@@ -496,6 +498,19 @@ def render_newtype(
     )
 
 
+def render_pydantic_type(
+    spec: PydanticTypeSpec,
+    link_ctx: LinkContext | None = None,
+    used_by: list[UsedByEntry] | None = None,
+) -> str:
+    """Render a PydanticTypeSpec as Markdown documentation."""
+    template = _get_jinja_env().get_template("pydantic_type.md.jinja2")
+    return template.render(
+        pydantic_type=spec,
+        used_by=_build_used_by_context(used_by, link_ctx),
+    )
+
+
 # Matches the ge/le bounds of the int64 NewType in overture.schema.system.primitive.
 _INT64_MIN = -(2**63)
 _INT64_MAX = 2**63 - 1

packages/overture-schema-codegen/src/overture/schema/codegen/markdown_type_format.py

@@ -62,6 +62,26 @@ def _linked_type_identity(ti: TypeInfo) -> TypeIdentity | None:
     return None
 
 
+def _try_primitive_link(
+    ti: TypeInfo, display_name: str, ctx: LinkContext | None
+) -> str | None:
+    """Try to link a PRIMITIVE type to its page via registry lookup.
+
+    Registered primitives (int32, Geometry) and Pydantic types (HttpUrl)
+    can have pages in the registry. Uses the type registry display name
+    (e.g. ``geometry`` not ``Geometry``) for the link text.
+    """
+    if ti.kind != TypeKind.PRIMITIVE or not ctx:
+        return None
+    candidate = ti.newtype_ref or ti.source_type
+    if candidate is None:
+        return None
+    href = ctx.resolve_link(TypeIdentity(candidate, display_name))
+    if href:
+        return _code_link(display_name, href)
+    return None
+
+
 def _markdown_type_name(ti: TypeInfo) -> str:
     """Return the markdown display name for a type.
 
@@ -129,7 +149,12 @@ def format_type(
             display = _wrap_list_n(display, ti.list_depth)
     else:
         base = resolve_type_name(ti, "markdown")
-        if ti.is_list:
+        link = _try_primitive_link(ti, base, ctx)
+        if link and ti.is_list:
+            display = _wrap_list_n(link, ti.list_depth)
+        elif link:
+            display = link
+        elif ti.is_list:
             display = _plain_list_type(base, ti.list_depth)
         else:
             display = f"`{base}`"

packages/overture-schema-codegen/src/overture/schema/codegen/path_assignment.py

@@ -9,7 +9,7 @@
 
 from .case_conversion import slug_filename
 from .module_layout import compute_output_dir, output_dir_for_entry_point
-from .specs import FeatureSpec, SupplementarySpec, TypeIdentity
+from .specs import FeatureSpec, PydanticTypeSpec, SupplementarySpec, TypeIdentity
 
 __all__ = [
     "GEOMETRY_PAGE",
@@ -48,6 +48,13 @@ def build_placement_registry(
     for tid, supp_spec in all_specs.items():
         if tid in registry:
             continue
+        if isinstance(supp_spec, PydanticTypeSpec):
+            registry[tid] = (
+                PurePosixPath("pydantic")
+                / supp_spec.source_module
+                / slug_filename(tid.name)
+            )
+            continue
         source_module = getattr(supp_spec.source_type, "__module__", None)
         if source_module is None:
             continue

packages/overture-schema-codegen/src/overture/schema/codegen/pydantic_extraction.py

@@ -0,0 +1,33 @@
+"""Pydantic built-in type extraction."""
+
+import re
+
+from .docstring import first_docstring_line
+from .specs import PydanticTypeSpec
+
+__all__ = ["extract_pydantic_type"]
+
+# Matches bare admonition labels like "Info:" or "Note:" with no following text.
+_ADMONITION_LABEL = re.compile(r"^\w+:\s*$")
+
+
+def _usable_description(doc: str | None) -> str | None:
+    """Return the first docstring line, or None if it's an admonition label."""
+    line = first_docstring_line(doc)
+    if line is None or _ADMONITION_LABEL.match(line):
+        return None
+    return line
+
+
+def extract_pydantic_type(cls: type) -> PydanticTypeSpec:
+    """Extract a PydanticTypeSpec from a Pydantic built-in type class."""
+    module = getattr(cls, "__module__", "")
+    if not module.startswith("pydantic"):
+        msg = f"Expected a pydantic type, got {cls!r} from {module!r}"
+        raise ValueError(msg)
+    return PydanticTypeSpec(
+        name=cls.__name__,
+        description=_usable_description(cls.__doc__),
+        source_type=cls,
+        source_module=cls.__module__.removeprefix("pydantic."),
+    )

packages/overture-schema-codegen/src/overture/schema/codegen/reverse_references.py

@@ -14,6 +14,7 @@
     SupplementarySpec,
     TypeIdentity,
     UnionSpec,
+    is_pydantic_type,
 )
 from .type_analyzer import TypeInfo, TypeKind, walk_type_info
 
@@ -94,6 +95,11 @@ def _visit(node: TypeInfo) -> None:
                     referrer_kind,
                 )
 
+            if is_pydantic_type(node):
+                add_reference(
+                    TypeIdentity.of(node.source_type), referrer, referrer_kind
+                )
+
             if node.union_members is not None:
                 for member_cls in node.union_members:
                     add_reference(

packages/overture-schema-codegen/src/overture/schema/codegen/specs.py

@@ -22,10 +22,13 @@
     "ModelSpec",
     "NewTypeSpec",
     "PrimitiveSpec",
+    "PydanticTypeSpec",
     "SupplementarySpec",
     "TypeIdentity",
     "filter_model_classes",
     "is_model_class",
+    "is_pydantic_sourced",
+    "is_pydantic_type",
     "is_union_alias",
 ]
 
@@ -59,8 +62,8 @@ def __hash__(self) -> int:
 class _SourceTypeIdentityMixin:
     """Mixin providing ``identity`` from ``source_type`` and ``name``.
 
-    Shared by EnumSpec, ModelSpec, and NewTypeSpec -- each has a
-    ``source_type`` (the Python class/callable) and a ``name``.
+    Shared by EnumSpec, ModelSpec, NewTypeSpec, and PydanticTypeSpec --
+    each has a ``source_type`` (the Python class/callable) and a ``name``.
     UnionSpec uses ``source_annotation`` instead, so it defines its
     own ``identity``.
     """
@@ -190,14 +193,46 @@ class PrimitiveSpec:
     float_bits: int | None = None
 
 
-SupplementarySpec = EnumSpec | NewTypeSpec | ModelSpec
+@dataclass
+class PydanticTypeSpec(_SourceTypeIdentityMixin):
+    """Specification for a Pydantic built-in type (HttpUrl, EmailStr, etc.)."""
+
+    name: str
+    description: str | None
+    source_type: type
+    source_module: str
+
+    @property
+    def docs_url(self) -> str:
+        """Pydantic documentation URL for this type."""
+        return (
+            f"https://docs.pydantic.dev/latest/api/{self.source_module}"
+            f"/#pydantic.{self.source_module}.{self.name}"
+        )
+
+
+SupplementarySpec = EnumSpec | NewTypeSpec | ModelSpec | PydanticTypeSpec
 """Non-feature types referenced by feature models.
 
 Excludes PrimitiveSpec and geometry types, which are extracted
 separately via dedicated functions.
 """
 
 
+def is_pydantic_sourced(source_type: type | None) -> bool:
+    """Check whether *source_type* originates from the ``pydantic`` package."""
+    return getattr(source_type, "__module__", "").startswith("pydantic")
+
+
+def is_pydantic_type(ti: TypeInfo) -> bool:
+    """Check whether a TypeInfo represents a Pydantic built-in type."""
+    return (
+        ti.kind == TypeKind.PRIMITIVE
+        and ti.source_type is not None
+        and is_pydantic_sourced(ti.source_type)
+    )
+
+
 def is_model_class(obj: object) -> TypeGuard[type[BaseModel]]:
     """Check whether *obj* is a concrete BaseModel subclass (not a type alias)."""
     return isinstance(obj, type) and issubclass(obj, BaseModel)

packages/overture-schema-codegen/src/overture/schema/codegen/templates/markdown/pydantic_type.md.jinja2

@@ -0,0 +1,8 @@
+# {{ pydantic_type.name }}
+{% if pydantic_type.description %}
+
+{{ pydantic_type.description | linkify_urls }}
+{% endif %}
+
+See: [Pydantic docs]({{ pydantic_type.docs_url }})
+{% include '_used_by.md.jinja2' %}

packages/overture-schema-codegen/src/overture/schema/codegen/type_collection.py

@@ -10,7 +10,15 @@
 from .enum_extraction import extract_enum
 from .model_extraction import extract_model
 from .newtype_extraction import extract_newtype
-from .specs import FeatureSpec, FieldSpec, ModelSpec, SupplementarySpec, TypeIdentity
+from .pydantic_extraction import extract_pydantic_type
+from .specs import (
+    FeatureSpec,
+    FieldSpec,
+    ModelSpec,
+    SupplementarySpec,
+    TypeIdentity,
+    is_pydantic_type,
+)
 from .type_analyzer import TypeInfo, TypeKind, analyze_type, is_newtype, walk_type_info
 from .type_registry import is_semantic_newtype
 
@@ -106,6 +114,12 @@ def _visit(node: TypeInfo) -> None:
                 if newly_registered:
                     _collect_inner_newtypes(node.newtype_ref)
 
+            if is_pydantic_type(node):
+                assert node.source_type is not None  # guaranteed by is_pydantic_type
+                pid = TypeIdentity.of(node.source_type)
+                if pid not in all_specs:
+                    all_specs[pid] = extract_pydantic_type(node.source_type)
+
         walk_type_info(ti, _visit)
 
     def _collect_from_fields(fields: list[FieldSpec]) -> None:

packages/overture-schema-codegen/tests/codegen_test_support.py

@@ -13,6 +13,7 @@
 
 import pytest
 from overture.schema.codegen.model_extraction import extract_model
+from overture.schema.codegen.pydantic_extraction import extract_pydantic_type
 from overture.schema.codegen.specs import (
     AnnotatedField,
     EnumMemberSpec,
@@ -37,7 +38,7 @@
 )
 from overture.schema.system.ref import Id, Identified, Reference, Relationship
 from overture.schema.system.string import HexColor, LanguageTag, StrippedString
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, EmailStr, Field, HttpUrl
 
 STR_TYPE = TypeInfo(base_type="str", kind=TypeKind.PRIMITIVE)
 
@@ -196,6 +197,17 @@ class FeatureWithDict(
     metadata: dict[str, int] = Field(description="Numeric metadata")
 
 
+class FeatureWithUrl(FeatureBase[Literal["test"], Literal["linked"]]):
+    """A feature with Pydantic URL and email fields."""
+
+    website: HttpUrl | None = None
+    emails: list[EmailStr] | None = None
+
+
+HTTP_URL_SPEC = extract_pydantic_type(HttpUrl)
+EMAIL_STR_SPEC = extract_pydantic_type(EmailStr)
+
+
 class SegmentBase(BaseModel):
     """Common base for test segments."""