feat(sbom): use annotated data types in Pydantic config

Replace generic `str` fields in SbomSettings and PurlConfig with
specialized annotated types that validate input and make the schema
self-documenting.

New annotated types:
- PurlType: strips, lowercases, rejects empty purl type strings
- RepositoryUrl: validates http/https URL with scheme and host
- UpstreamPurl: validates purl strings via PackageURL.from_string()
- SpdxNamespace: validates SPDX documentNamespace as a URL
- SpdxActor: validates SPDX actor format (Organization/Person/Tool/NOASSERTION)

The @field_validator on PurlConfig.upstream is replaced by the
UpstreamPurl annotated type, moving validation into the type itself.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Closes: #1072
Signed-off-by: Shanmukh Pawan <smoparth@redhat.com>

Author: smoparth

src/fromager/packagesettings/__init__.py

@@ -25,8 +25,13 @@
     Package,
     PackageVersion,
     PatchMap,
+    PurlType,
     RawAnnotations,
+    RepositoryUrl,
+    SpdxActor,
+    SpdxNamespace,
     Template,
+    UpstreamPurl,
     Variant,
     VariantChangelog,
 )
@@ -48,12 +53,17 @@
     "PatchMap",
     "ProjectOverride",
     "PurlConfig",
+    "PurlType",
     "RawAnnotations",
+    "RepositoryUrl",
     "ResolverDist",
     "SbomSettings",
     "Settings",
     "SettingsFile",
+    "SpdxActor",
+    "SpdxNamespace",
     "Template",
+    "UpstreamPurl",
     "Variant",
     "VariantChangelog",
     "VariantInfo",

src/fromager/packagesettings/_models.py

@@ -10,7 +10,6 @@
 
 import pydantic
 import yaml
-from packageurl import PackageURL
 from packaging.requirements import Requirement
 from packaging.utils import canonicalize_name
 from pydantic import Field
@@ -21,8 +20,13 @@
     BuildDirectory,
     EnvVars,
     Package,
+    PurlType,
     RawAnnotations,
+    RepositoryUrl,
+    SpdxActor,
+    SpdxNamespace,
     Template,
+    UpstreamPurl,
     Variant,
     VariantChangelog,
 )
@@ -46,22 +50,22 @@ class SbomSettings(pydantic.BaseModel):
 
     model_config = MODEL_CONFIG
 
-    supplier: str = "NOASSERTION"
+    supplier: SpdxActor = "NOASSERTION"
     """SPDX supplier field for the wheel package (e.g. ``Organization: ExampleCo``)"""
 
-    namespace: str = "https://spdx.org/spdxdocs"
+    namespace: SpdxNamespace = "https://spdx.org/spdxdocs"
     """Base URL for the SPDX documentNamespace"""
 
-    creators: list[str] = Field(default_factory=list)
+    creators: list[SpdxActor] = Field(default_factory=list)
     """Additional SPDX creator entries (e.g. ``Organization: ExampleCo``)
 
     The fromager tool creator entry is always added automatically.
     """
 
-    purl_type: str = "pypi"
+    purl_type: PurlType = "pypi"
     """Default purl type for all packages (e.g. ``pypi``, ``generic``)"""
 
-    repository_url: str | None = None
+    repository_url: RepositoryUrl | None = None
     """Default purl ``repository_url`` qualifier for all packages
 
     When set, this URL is added to every purl as a qualifier
@@ -89,7 +93,7 @@ class PurlConfig(pydantic.BaseModel):
 
     model_config = MODEL_CONFIG
 
-    type: str | None = None
+    type: PurlType | None = None
     """Override the purl type (e.g. ``generic`` instead of ``pypi``)"""
 
     namespace: str | None = None
@@ -101,13 +105,13 @@ class PurlConfig(pydantic.BaseModel):
     version: str | None = None
     """Override the purl version component (defaults to the resolved version)"""
 
-    repository_url: str | None = None
+    repository_url: RepositoryUrl | None = None
     """Per-package override for the purl ``repository_url`` qualifier.
 
     Overrides the global ``sbom.repository_url`` setting for this package.
     """
 
-    upstream: str | None = None
+    upstream: UpstreamPurl | None = None
     """Full purl string identifying the upstream source package.
 
     When set, this is used as the upstream identity in the SBOM's
@@ -118,18 +122,6 @@ class PurlConfig(pydantic.BaseModel):
     purl without the ``repository_url`` qualifier.
     """
 
-    @pydantic.field_validator("upstream")
-    @classmethod
-    def validate_upstream_purl(cls, v: str | None) -> str | None:
-        """Validate that upstream is a valid purl string."""
-        if v is None:
-            return v
-        try:
-            PackageURL.from_string(v)
-        except ValueError as err:
-            raise ValueError(f"invalid upstream purl {v!r}") from err
-        return v
-
 
 class ResolverDist(pydantic.BaseModel):
     """Packages resolver dist

src/fromager/packagesettings/_typedefs.py

@@ -3,10 +3,13 @@
 from __future__ import annotations
 
 import pathlib
+import re
 import typing
 from collections.abc import Mapping
+from urllib.parse import urlparse
 
 import pydantic
+from packageurl import PackageURL
 from packaging.utils import NormalizedName, canonicalize_name
 from packaging.version import Version
 from pydantic_core import CoreSchema, core_schema
@@ -98,6 +101,99 @@ def _validate_envkey(v: typing.Any) -> str:
 GlobalChangelog = Mapping[Variant, list[str]]
 VariantChangelog = Mapping[PackageVersion, list[str]]
 
+_SPDX_ACTOR_RE = re.compile(r"^(Organization|Person|Tool):\s+\S.*$", flags=re.DOTALL)
+
+
+def _validate_url(v: str) -> str:
+    """Validate that *v* has an ``http`` or ``https`` scheme and a host."""
+    if not isinstance(v, str):
+        raise TypeError(f"expected str, got {type(v)}: {v!r}")
+    v = v.strip()
+    parsed = urlparse(v)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"URL must use http or https scheme, got {v!r}")
+    if not parsed.netloc:
+        raise ValueError(f"URL is missing a host/netloc component: {v!r}")
+    return v
+
+
+# purl type (e.g. "pypi", "generic", "github")
+def _validate_purl_type(v: str) -> str:
+    """Strip, lowercase, and reject empty purl type strings."""
+    if not isinstance(v, str):
+        raise TypeError(f"expected str, got {type(v)}: {v!r}")
+    v = v.strip().lower()
+    if not v:
+        raise ValueError("purl type must not be empty")
+    return v
+
+
+PurlType = typing.Annotated[
+    str,
+    pydantic.BeforeValidator(_validate_purl_type),
+]
+
+
+# repository URL used as a purl qualifier
+RepositoryUrl = typing.Annotated[
+    str,
+    pydantic.BeforeValidator(_validate_url),
+]
+
+
+# full purl string identifying an upstream source package
+def _validate_upstream_purl(v: str) -> str:
+    """Validate that *v* is a well-formed purl string."""
+    if not isinstance(v, str):
+        raise TypeError(f"expected str, got {type(v)}: {v!r}")
+    v = v.strip()
+    try:
+        PackageURL.from_string(v)
+    except ValueError as err:
+        raise ValueError(f"invalid upstream purl {v!r}: {err}") from err
+    return v
+
+
+UpstreamPurl = typing.Annotated[
+    str,
+    pydantic.BeforeValidator(_validate_upstream_purl),
+]
+
+
+# SPDX documentNamespace base URL
+SpdxNamespace = typing.Annotated[
+    str,
+    pydantic.BeforeValidator(_validate_url),
+]
+
+
+# SPDX actor value for supplier / creator fields
+def _validate_spdx_actor(v: str) -> str:
+    """Validate SPDX 2.3 actor format.
+
+    Must be ``NOASSERTION`` or ``<Category>: <name>`` where
+    category is ``Organization``, ``Person``, or ``Tool``.
+    """
+    if not isinstance(v, str):
+        raise TypeError(f"expected str, got {type(v)}: {v!r}")
+    v = v.strip()
+    if v == "NOASSERTION":
+        return v
+    if not _SPDX_ACTOR_RE.match(v):
+        raise ValueError(
+            f"SPDX actor must be 'NOASSERTION' or "
+            f"'Organization: <name>' / 'Person: <name>' / 'Tool: <name>', "
+            f"got {v!r}"
+        )
+    return v
+
+
+SpdxActor = typing.Annotated[
+    str,
+    pydantic.BeforeValidator(_validate_spdx_actor),
+]
+
+
 # Annotations
 RawAnnotations = Mapping[str, str]
 

tests/test_packagesettings.py

@@ -17,9 +17,14 @@
     Package,
     PackageBuildInfo,
     PackageSettings,
+    PurlType,
+    RepositoryUrl,
     ResolverDist,
     Settings,
     SettingsFile,
+    SpdxActor,
+    SpdxNamespace,
+    UpstreamPurl,
     Variant,
     substitute_template,
 )
@@ -490,6 +495,80 @@ def test_type_builddirectory() -> None:
         ta.validate_python("/absolute/path")
 
 
+def test_type_purl_type() -> None:
+    """Verify PurlType normalizes and rejects empty strings."""
+    ta = pydantic.TypeAdapter(PurlType)
+    assert ta.validate_python("pypi") == "pypi"
+    assert ta.validate_python("  Generic  ") == "generic"
+    assert ta.validate_python("GITHUB") == "github"
+    with pytest.raises(ValueError):
+        ta.validate_python("")
+    with pytest.raises(ValueError):
+        ta.validate_python("   ")
+
+
+def test_type_repository_url() -> None:
+    """Verify RepositoryUrl accepts valid URLs and rejects invalid ones."""
+    ta = pydantic.TypeAdapter(RepositoryUrl)
+    assert (
+        ta.validate_python("https://example.com/simple") == "https://example.com/simple"
+    )
+    assert (
+        ta.validate_python("http://packages.redhat.com") == "http://packages.redhat.com"
+    )
+    assert ta.validate_python("  https://example.com  ") == "https://example.com"
+    with pytest.raises(ValueError):
+        ta.validate_python("not-a-url")
+    with pytest.raises(ValueError):
+        ta.validate_python("ftp://files.example.com")
+    with pytest.raises(ValueError):
+        ta.validate_python("")
+
+
+def test_type_upstream_purl() -> None:
+    """Verify UpstreamPurl accepts valid purls and rejects invalid strings."""
+    ta = pydantic.TypeAdapter(UpstreamPurl)
+    assert ta.validate_python("pkg:pypi/flask@2.0") == "pkg:pypi/flask@2.0"
+    assert (
+        ta.validate_python("pkg:github/vllm-project/bart-plugin@v0.2.0")
+        == "pkg:github/vllm-project/bart-plugin@v0.2.0"
+    )
+    with pytest.raises(ValueError):
+        ta.validate_python("invalid-not-purl")
+    with pytest.raises(ValueError):
+        ta.validate_python("")
+
+
+def test_type_spdx_namespace() -> None:
+    """Verify SpdxNamespace accepts valid URLs and rejects invalid ones."""
+    ta = pydantic.TypeAdapter(SpdxNamespace)
+    assert (
+        ta.validate_python("https://spdx.org/spdxdocs") == "https://spdx.org/spdxdocs"
+    )
+    assert ta.validate_python("https://www.example.com") == "https://www.example.com"
+    with pytest.raises(ValueError):
+        ta.validate_python("not-a-url")
+    with pytest.raises(ValueError):
+        ta.validate_python("")
+
+
+def test_type_spdx_actor() -> None:
+    """Verify SpdxActor accepts valid SPDX actor formats."""
+    ta = pydantic.TypeAdapter(SpdxActor)
+    assert ta.validate_python("NOASSERTION") == "NOASSERTION"
+    assert ta.validate_python("Organization: ExampleCo") == "Organization: ExampleCo"
+    assert ta.validate_python("Person: Jane Doe") == "Person: Jane Doe"
+    assert ta.validate_python("Tool: fromager-1.0") == "Tool: fromager-1.0"
+    with pytest.raises(ValueError):
+        ta.validate_python("ExampleCo")
+    with pytest.raises(ValueError):
+        ta.validate_python("Organization:")
+    with pytest.raises(ValueError):
+        ta.validate_python("Organization: ")
+    with pytest.raises(ValueError):
+        ta.validate_python("")
+
+
 def test_global_settings(testdata_path: pathlib.Path) -> None:
     filename = testdata_path / "context/overrides/settings.yaml"
     gs = SettingsFile.from_file(filename)