Python SDK Models, Validation & Reflection

Pydantic models, field aliases, validation and reflection in the planned Python SDK.

The Python SDK models are planned as Pydantic v2 models generated from the official OpenAPI contract. Generated models are the source for runtime validation, JSON serialization and field reflection.

Python names and JSON aliases

Python code uses snake_case field names. JSON sent to the API uses the backend camelCase aliases.

Python
from conformaesg.models import SupplierCreate


payload = SupplierCreate(
    name="Acme Textiles Ltd",
    vat_number="IT01234567890",
    contact_email="procurement@example.com",
)


json_payload = payload.model_dump(by_alias=True, exclude_none=True)

The serialized payload uses aliases such as vatNumber and contactEmail.

Input and response validation

Input payloads are validated before the HTTP request. JSON responses are validated before they are returned to application code.

Python
from pydantic import ValidationError


from conformaesg.models import SupplierCreate


try:
    SupplierCreate(name="", category="TEXTILES")
except ValidationError as exc:
    print(exc.errors())

Validation errors should include the field path and OpenAPI description when the generated schema provides one.

Reflection API

Generated models expose field metadata for dynamic forms, import mappers and admin tooling:

Python
from conformaesg.models import SupplierCreate


for field in SupplierCreate.describe_fields():
    print(field.name, field.python_name, field.alias, field.required)


print(SupplierCreate.field_description("vat_number"))
print(SupplierCreate.model_json_schema())

describe_fields() returns stable metadata:

Python
[
    FieldInfo(
        name="vat_number",
        python_name="vat_number",
        alias="vatNumber",
        type="str",
        required=False,
        description="Description from OpenAPI when available.",
        examples=[],
    )
]

Field descriptions must come from OpenAPI. If a description is missing or too vague, update the backend DTO/OpenAPI source in a separate API workstream rather than writing divergent SDK-only descriptions.

Type checking

The package is planned as type-aware through py.typed.

Recommended project setup:

TOML
[tool.mypy]
python_version = "3.10"
strict = true

or configure Pyright in strict mode. Public SDK methods should have concrete payload and response types, not dict[str, Any] as the main API surface.