Implement governed tabular source snapshots

src/govoplan_connectors/backend/schemas.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class SnapshotCreateRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=300)
+    source_name: str = Field(
+        min_length=1,
+        max_length=120,
+        pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
+    )
+    description: str | None = Field(default=None, max_length=4000)
+    format: Literal["json", "csv"] = "json"
+    rows: list[dict[str, Any]] | None = Field(default=None, max_length=10_000)
+    csv_text: str | None = Field(default=None, max_length=5_000_000)
+    delimiter: Literal[",", ";", "\t", "|"] = ","
+
+    @model_validator(mode="after")
+    def validate_payload(self) -> "SnapshotCreateRequest":
+        if self.format == "json" and self.rows is None:
+            raise ValueError("JSON snapshots require rows.")
+        if self.format == "json" and self.csv_text is not None:
+            raise ValueError("JSON snapshots cannot include CSV text.")
+        if self.format == "csv" and not self.csv_text:
+            raise ValueError("CSV snapshots require CSV text.")
+        if self.format == "csv" and self.rows is not None:
+            raise ValueError("CSV snapshots cannot include JSON rows.")
+        return self
+
+
+class TabularColumnResponse(BaseModel):
+    name: str
+    data_type: str
+    nullable: bool
+
+
+class TabularSourceResponse(BaseModel):
+    ref: str
+    provider: str
+    source_name: str
+    name: str
+    description: str | None
+    columns: list[TabularColumnResponse]
+    schema_version: str
+    fingerprint: str
+    row_count: int | None
+    byte_count: int | None
+    updated_at: str | None
+    capabilities: list[str]
+    metadata: dict[str, Any]
+
+
+class TabularSourceListResponse(BaseModel):
+    sources: list[TabularSourceResponse]
+
+
+class TabularSourcePreviewResponse(BaseModel):
+    source: TabularSourceResponse
+    rows: list[dict[str, Any]]
+    total_rows: int
+    truncated: bool
+
+
+class TabularSourceDeleteResponse(BaseModel):
+    deleted: bool
+    source_ref: str
+
+
+__all__ = [
+    "SnapshotCreateRequest",
+    "TabularColumnResponse",
+    "TabularSourceDeleteResponse",
+    "TabularSourceListResponse",
+    "TabularSourcePreviewResponse",
+    "TabularSourceResponse",
+]