SDL — Structured Data Layer: type the meaning of fields so Webbee reads your entities as data, with typed facets and roles instead of field-name guessing.

sdl (Structured Data Layer) is the typed-entity system for @chat.function return values. Instead of returning a plain dict inside ActionResult, you compose sdl.Entity with one or more facets — thin mixins that attach semantically-tagged fields to your entity class. Every facet field carries a standard role (e.g. time.created_at, task.priority) so the platform knows exactly what each field means regardless of your extension's naming conventions.

SDL ships in SDK 5.2.0 and is live in production — the platform reads the SDL entities your extensions return today. SDL is fully additive and opt-in: attach a data_model= that subclasses sdl.Entity and you are using SDL; all existing dict-based data payloads continue to work.

Quick start

Subclass sdl.Entity, mix in the facets that match your entity's semantics, and pass the model class to data_model=. Return an instance of it inside ActionResult.success().

from imperal_sdk import sdl
from imperal_sdk.chat import ChatExtension, ActionResult

chat = ChatExtension(...)

class Task(sdl.Entity, sdl.Schedulable, sdl.Prioritized, sdl.Progress):
    estimate_s: int | None = None

@chat.function(
    "get_task",
    description="Open a task by ID.",
    action_type="read",
    data_model=Task,
)
async def get_task(ctx, params) -> ActionResult:
    return ActionResult.success(
        Task(id=7, title="Ship SDL", priority="high", progress=0.5),
        summary="Task loaded.",
    )

The data_model=Task declaration makes the entity's shape visible to the platform and to downstream chain steps — without any changes to how you write the handler body.

Core types

`sdl.Entity`

The canonical base class. Every SDL entity is a Pydantic model that inherits from sdl.Entity.

Required fields:

Field	Type	Notes
`id`	`str \| int`	Stable identifier for this entity.
`title`	`str`	Human-readable name shown in the platform.
`kind`	`str`	Semantic type label. Defaults to the subclass class-name lowercased. `class Project(sdl.Entity)` → kind `"project"`.

Optional display fields:

Field	Type	Notes
`subtitle`	`str \| None`	Secondary display line (e.g. category, assignee name).
`description`	`str \| None`	Longer plain-text description.
`status`	`str \| None`	Human-readable status label.
`url`	`str \| None`	Deep-link URL into the source application.

sdl.Entity carries an x-sdl: "entity" schema marker. The platform uses this marker to detect SDL results — you do not need to set it manually.

Subclass sdl.Entity and add your own extension-specific fields alongside any standard facet mixins:

from imperal_sdk import sdl

class Project(sdl.Entity):
    repo_url: str | None = None
    default_branch: str = "main"

class ProjectWithTiming(sdl.Entity, sdl.Timestamped, sdl.Schedulable):
    repo_url: str | None = None

`sdl.Ref`

A lightweight reference to another entity. Use it for relations, list items, and cross-app links where you want to name the target without embedding the full entity.

Field	Type	Notes
`id`	`str \| int`	ID of the referenced entity.
`kind`	`str`	Entity kind of the target (e.g. `"project"`, `"user"`).
`title`	`str`	Human-readable name. Included so the platform can render the reference without a second call.
`app_id`	`str \| None`	App that owns the referenced entity. Defaults to the current app when omitted.

from imperal_sdk import sdl

class Task(sdl.Entity, sdl.Assignable):
    project: sdl.Ref | None = None

task = Task(
    id=42,
    title="Fix login bug",
    assignee=sdl.Ref(id="u_123", kind="user", title="Alex"),
    project=sdl.Ref(id="p_7", kind="project", title="Auth Service"),
)

`sdl.EntityList[T]`

A typed list result that wraps a homogeneous list of entities with pagination metadata.

Field	Type	Notes
`items`	`list[T]`	The entities in this page.
`total`	`int \| None`	Total count across all pages, if known.
`page`	`int \| None`	Current page number (1-based), if applicable.
`has_more`	`bool`	Whether additional pages are available.

sdl.EntityList carries an x-sdl: "entity-list" schema marker.

When passing to data_model=, use a concrete subclass rather than the raw generic. Pydantic requires a concrete class at the point of instantiation:

from imperal_sdk import sdl

class Project(sdl.Entity):
    repo_url: str | None = None

class ProjectList(sdl.EntityList[Project]):
    pass

@chat.function(
    "list_projects",
    description="List all projects.",
    action_type="read",
    data_model=ProjectList,
)
async def list_projects(ctx, params) -> ActionResult:
    rows = await ctx.store.query("projects")
    projects = [Project(id=r.id, title=r.data["name"]) for r in rows.data]
    return ActionResult.success(
        ProjectList(items=projects, total=len(projects), has_more=False),
        summary=f"{len(projects)} project(s).",
    )

Custom roles — `sdl.field`

For fields not covered by any standard facet, attach a role with sdl.field(role="...").

from imperal_sdk import sdl

class Invoice(sdl.Entity, sdl.Invoiced):
    po_number: str | None = sdl.field(role="billing.po_number")
    vendor_code: str | None = sdl.field(role="billing.vendor_code")

Role format: dotted lowercase — yourapp.something. Use your app ID or a domain you own as the namespace prefix.

Reserved namespaces are owned by the standard facets and must not be used for custom roles:

core · time · people · content · comm · media · quantity · money · catalog · task · geo · net · metric · event · rating · sec · device

For human descriptions on custom fields, use native Pydantic Field(description=...):

from pydantic import Field
from imperal_sdk import sdl

class Shipment(sdl.Entity):
    carrier_code: str | None = sdl.field(
        role="logistics.carrier_code",
        description="IATA carrier code, e.g. 'UPS', 'FEDEX'.",
    )

Introspection — `sdl.roles_of`

sdl.roles_of(model) -> dict[str, str]

Returns a {field_name: role} map for an Entity subclass or an instance. This is how tooling reads an entity's semantic shape — for example, to discover which fields carry time-family roles or task-family roles before deciding how to render them.

from imperal_sdk import sdl

class Task(sdl.Entity, sdl.Schedulable, sdl.Prioritized):
    pass

print(sdl.roles_of(Task))
# {
#   "id": "core.id",
#   "title": "core.title",
#   "kind": "core.kind",
#   "start_at": "time.start_at",
#   "end_at": "time.end_at",
#   "due_at": "time.due_at",
#   "all_day": "time.all_day",
#   "timezone": "time.timezone",
#   "priority": "task.priority",
#   "urgency": "task.urgency",
#   "severity": "task.severity",
#   ...
# }

All 17 families and 123 facets. All facet fields are optional — every field defaults to None (or [] for list fields). Mix any combination into the same entity without field-name conflicts.

Identity & Provenance (`core.*`)

Localization, versioning, iconography, and lifecycle state.

Localized

Multi-language metadata.

Fields: language, languages, text_direction, locale, localized_title, localized_description, available_locales

class Article(sdl.Entity, sdl.Localized):
    pass

SDL — Structured Data Layer

@chat.function reference