feat: generate user-facing write/read schema models + offline validation

.gitignore

@@ -30,6 +30,9 @@ dist/*
 
 # Generated files
 generated/
+# Committed, generated schema models (write/read variants) must be version-controlled.
+!infrahub_sdk/schema/generated/
+!infrahub_sdk/schema/generated/*.py
 sandbox/
 
 # hatch-vcs version file (written at build time; must not be tracked)

changelog/+infp-234-sdk-schema-models.changed.md

@@ -0,0 +1,7 @@
+The hand-maintained schema models in `infrahub_sdk.schema` are now backed by the generated write/read contract (`infrahub_sdk.schema.generated`). Public names, import paths, and behavior methods are unchanged, but a few defaults and constraints now match the server contract:
+
+- `AttributeKind.STRING` has been removed. It was deprecated and `kind="String"` was already rejected server-side; use `AttributeKind.TEXT` instead.
+- Write and read models drop unknown fields silently (`extra="ignore"`). A submitted field that is not part of the write contract — read-level, internal, or a typo — is dropped rather than rejected, and a read model tolerates additional fields returned by a newer server.
+- Write-model defaults now match the server contract: relationship `min_count`/`max_count` default to `0` (was `None`), node `branch` defaults to `"aware"`, `generate_profile` defaults to `True`, and `generate_template` defaults to `False`. This changes the round-trip output of programmatically-built schemas.
+
+Constructing `AttributeSchema(name=..., kind=AttributeKind.TEXT, ...)`, `NodeSchema`, `GenericSchema`, `RelationshipSchema`, `SchemaRoot`, and the read-side `*API` models continues to work unchanged.

infrahub_sdk/protocols.py

@@ -222,6 +222,7 @@ class CoreTransformation(CoreNode):
     query: RelatedNode
     repository: RelatedNode
     tags: RelationshipManager
+    artifact_definitions: RelationshipManager
 
 
 class CoreTriggerRule(CoreNode):
@@ -314,6 +315,8 @@ class CoreArtifactDefinition(CoreTaskTarget):
     fingerprint: StringOptional
     targets: RelatedNode
     transformation: RelatedNode
+    artifacts: RelationshipManager
+    validators: RelationshipManager
 
 
 class CoreArtifactThread(CoreThread):
@@ -345,6 +348,7 @@ class CoreCheckDefinition(CoreTaskTarget):
     query: RelatedNode
     targets: RelatedNode
     tags: RelationshipManager
+    validators: RelationshipManager
 
 
 class CoreCustomWebhook(CoreWebhook, CoreTaskTarget):
@@ -405,6 +409,8 @@ class CoreGeneratorDefinition(CoreTaskTarget):
     query: RelatedNode
     repository: RelatedNode
     targets: RelatedNode
+    instances: RelationshipManager
+    validators: RelationshipManager
 
 
 class CoreGeneratorGroup(CoreGroup):
@@ -439,6 +445,7 @@ class CoreGraphQLQuery(CoreNode):
     height: IntegerOptional
     repository: RelatedNode
     tags: RelationshipManager
+    query_groups: RelationshipManager
 
 
 class CoreGraphQLQueryGroup(CoreGroup):
@@ -820,6 +827,7 @@ class CoreTransformationSync(CoreNodeSync):
     query: RelatedNodeSync
     repository: RelatedNodeSync
     tags: RelationshipManagerSync
+    artifact_definitions: RelationshipManagerSync
 
 
 class CoreTriggerRuleSync(CoreNodeSync):
@@ -912,6 +920,8 @@ class CoreArtifactDefinitionSync(CoreTaskTargetSync):
     fingerprint: StringOptional
     targets: RelatedNodeSync
     transformation: RelatedNodeSync
+    artifacts: RelationshipManagerSync
+    validators: RelationshipManagerSync
 
 
 class CoreArtifactThreadSync(CoreThreadSync):
@@ -943,6 +953,7 @@ class CoreCheckDefinitionSync(CoreTaskTargetSync):
     query: RelatedNodeSync
     targets: RelatedNodeSync
     tags: RelationshipManagerSync
+    validators: RelationshipManagerSync
 
 
 class CoreCustomWebhookSync(CoreWebhookSync, CoreTaskTargetSync):
@@ -1003,6 +1014,8 @@ class CoreGeneratorDefinitionSync(CoreTaskTargetSync):
     query: RelatedNodeSync
     repository: RelatedNodeSync
     targets: RelatedNodeSync
+    instances: RelationshipManagerSync
+    validators: RelationshipManagerSync
 
 
 class CoreGeneratorGroupSync(CoreGroupSync):
@@ -1037,6 +1050,7 @@ class CoreGraphQLQuerySync(CoreNodeSync):
     height: IntegerOptional
     repository: RelatedNodeSync
     tags: RelationshipManagerSync
+    query_groups: RelationshipManagerSync
 
 
 class CoreGraphQLQueryGroupSync(CoreGroupSync):

infrahub_sdk/protocols_base.py

@@ -7,7 +7,7 @@
 
     from .context import RequestContext
     from .node.metadata import NodeMetadata
-    from .schema import MainSchemaTypes
+    from .schema import MainSchemaTypesAPI
 
 
 @runtime_checkable
@@ -181,7 +181,7 @@ class AnyAttributeOptional(Attribute):
 
 
 class CoreNodeBase:
-    _schema: MainSchemaTypes
+    _schema: MainSchemaTypesAPI
     _internal_id: str
     id: str  # NOTE this is incorrect, should be str | None
     display_label: str | None

infrahub_sdk/schema/__init__.py

@@ -24,6 +24,8 @@
 from ..protocols_base import CoreNodeBase
 from ..queries import SCHEMA_HASH_SYNC_STATUS
 from .export import RESTRICTED_NAMESPACES, NamespaceExport, SchemaExport, schema_to_export_dict
+from .generated.read import InfrahubSchemaRead
+from .generated.write import InfrahubSchemaWrite
 from .main import (
     AttributeSchema,
     AttributeSchemaAPI,
@@ -42,6 +44,7 @@
     SchemaRootAPI,
     TemplateSchemaAPI,
 )
+from .validate import SchemaValidationErrorDetail, SchemaValidationResult, validate_schema
 
 if TYPE_CHECKING:
     from ..client import InfrahubClient, InfrahubClientSync, SchemaType, SchemaTypeSync
@@ -56,6 +59,8 @@
     "BranchSupportType",
     "GenericSchema",
     "GenericSchemaAPI",
+    "InfrahubSchemaRead",
+    "InfrahubSchemaWrite",
     "NamespaceExport",
     "NodeSchema",
     "NodeSchemaAPI",
@@ -67,8 +72,11 @@
     "SchemaExport",
     "SchemaRoot",
     "SchemaRootAPI",
+    "SchemaValidationErrorDetail",
+    "SchemaValidationResult",
     "TemplateSchemaAPI",
     "schema_to_export_dict",
+    "validate_schema",
 ]
 
 
@@ -166,7 +174,9 @@ def _build_export_schemas(
         return SchemaExport(namespaces=ns_map)
 
     def validate(self, data: dict[str, Any]) -> None:
-        SchemaRoot(**data)
+        # Validate against the generated write contract so this matches what /api/schema/load
+        # enforces (unknown keys rejected, attribute kinds discriminated, extensions understood).
+        InfrahubSchemaWrite.model_validate(data)
 
     def validate_data_against_schema(self, schema: MainSchemaTypesAPI, data: dict) -> None:
         for key in data:
@@ -362,7 +372,9 @@ async def load(
         branch = branch or self.client.default_branch
         url = f"{self.client.address}/api/schema/load?branch={branch}"
         response = await self.client._post(
-            url=url, timeout=max(120, self.client.default_timeout), payload={"schemas": schemas}
+            url=url,
+            timeout=max(120, self.client.default_timeout),
+            payload={"schemas": schemas},
         )
 
         if wait_until_converged:
@@ -394,7 +406,9 @@ async def check(self, schemas: list[dict], branch: str | None = None) -> tuple[b
         branch = branch or self.client.default_branch
         url = f"{self.client.address}/api/schema/check?branch={branch}"
         response = await self.client._post(
-            url=url, timeout=max(120, self.client.default_timeout), payload={"schemas": schemas}
+            url=url,
+            timeout=max(120, self.client.default_timeout),
+            payload={"schemas": schemas},
         )
 
         if response.status_code == httpx.codes.ACCEPTED:
@@ -892,7 +906,9 @@ def load(
         branch = branch or self.client.default_branch
         url = f"{self.client.address}/api/schema/load?branch={branch}"
         response = self.client._post(
-            url=url, timeout=max(120, self.client.default_timeout), payload={"schemas": schemas}
+            url=url,
+            timeout=max(120, self.client.default_timeout),
+            payload={"schemas": schemas},
         )
 
         if wait_until_converged:
@@ -924,7 +940,9 @@ def check(self, schemas: list[dict], branch: str | None = None) -> tuple[bool, d
         branch = branch or self.client.default_branch
         url = f"{self.client.address}/api/schema/check?branch={branch}"
         response = self.client._post(
-            url=url, timeout=max(120, self.client.default_timeout), payload={"schemas": schemas}
+            url=url,
+            timeout=max(120, self.client.default_timeout),
+            payload={"schemas": schemas},
         )
 
         if response.status_code == httpx.codes.ACCEPTED:

infrahub_sdk/schema/generated/__init__.py

@@ -0,0 +1,4 @@
+# Generated by "invoke backend.generate", do not edit directly
+from . import enums, read, write
+
+__all__ = ["enums", "read", "write"]

infrahub_sdk/schema/generated/enums.py

@@ -0,0 +1,84 @@
+# Generated by "invoke backend.generate", do not edit directly
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class BranchSupportType(str, Enum):
+    AWARE = "aware"
+    AGNOSTIC = "agnostic"
+    LOCAL = "local"
+
+
+class RelationshipKind(str, Enum):
+    GENERIC = "Generic"
+    ATTRIBUTE = "Attribute"
+    COMPONENT = "Component"
+    PARENT = "Parent"
+    GROUP = "Group"
+    HIERARCHY = "Hierarchy"
+    PROFILE = "Profile"
+    TEMPLATE = "Template"
+
+
+class RelationshipCardinality(str, Enum):
+    ONE = "one"
+    MANY = "many"
+
+
+class RelationshipDirection(str, Enum):
+    BIDIR = "bidirectional"
+    OUTBOUND = "outbound"
+    INBOUND = "inbound"
+
+
+class RelationshipDeleteBehavior(str, Enum):
+    NO_ACTION = "no-action"
+    CASCADE = "cascade"
+
+
+class AllowOverrideType(str, Enum):
+    NONE = "none"
+    ANY = "any"
+
+
+class SchemaState(str, Enum):
+    PRESENT = "present"
+    ABSENT = "absent"
+
+
+class SchemaAttributeDisplay(str, Enum):
+    DEFAULT = "default"
+    EXTRA = "extra"
+
+
+class ComputedAttributeKind(str, Enum):
+    USER = "User"
+    JINJA2 = "Jinja2"
+    TRANSFORM_PYTHON = "TransformPython"
+
+
+class AttributeKind(str, Enum):
+    ID = "ID"
+    DROPDOWN = "Dropdown"
+    TEXT = "Text"
+    TEXTAREA = "TextArea"
+    DATETIME = "DateTime"
+    EMAIL = "Email"
+    PASSWORD = "Password"
+    HASHEDPASSWORD = "HashedPassword"
+    URL = "URL"
+    FILE = "File"
+    MAC_ADDRESS = "MacAddress"
+    COLOR = "Color"
+    NUMBER = "Number"
+    NUMBERPOOL = "NumberPool"
+    BANDWIDTH = "Bandwidth"
+    IPHOST = "IPHost"
+    IPNETWORK = "IPNetwork"
+    BOOLEAN = "Boolean"
+    CHECKBOX = "Checkbox"
+    LIST = "List"
+    JSON = "JSON"
+    ANY = "Any"