procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/dto/data/action_families.json

@@ -0,0 +1,55 @@
+{
+  "_note": "Curated action name -> {family, desc} grouping. Source of truth for inspect-flow's action_families bucket and list-actions-catalog --by-family. Seeded from PROCESIO-RESOURCE-MODEL-NOTES.md §2 (the common actions). Actions not listed bucket as 'other'.",
+  "families": ["control", "subprocess", "scripting", "data", "integration", "datetime", "file", "document", "other"],
+  "actions": {
+    "Start": {"family": "control", "desc": "flow source"},
+    "Stop": {"family": "control", "desc": "flow terminal"},
+    "Decisional": {"family": "control", "desc": "branch (N-way cases + default)"},
+    "Join": {"family": "control", "desc": "merge branches back to one path"},
+    "For Each": {"family": "control", "desc": "loop over a list (renders as an area)"},
+    "Delay": {"family": "control", "desc": "wait"},
+    "Throw": {"family": "control", "desc": "raise a controlled error into the error port"},
+    "Call Subprocess": {"family": "subprocess", "desc": "run another process synchronously, map vars"},
+    "Trigger Subprocess": {"family": "subprocess", "desc": "fire another process async"},
+    "Node": {"family": "scripting", "desc": "NodeJS script (raw typed output; needs Timeout>0)"},
+    "Javascript": {"family": "scripting", "desc": "JS script (output wrapped {result})"},
+    "Python": {"family": "scripting", "desc": "Python script"},
+    "Map Data": {"family": "data", "desc": "copy/transform variables between shapes"},
+    "Extract Objects": {"family": "data", "desc": "pull objects out of a collection/JSON"},
+    "Extract List": {"family": "data", "desc": "pull a list out of data"},
+    "Extract Object": {"family": "data", "desc": "pull one object out of data"},
+    "Extract Text": {"family": "data", "desc": "extract text"},
+    "String To JSON": {"family": "data", "desc": "parse a string into JSON"},
+    "Object To String": {"family": "data", "desc": "serialize an object to string"},
+    "Object To File": {"family": "data", "desc": "write an object to a file"},
+    "Get Element": {"family": "data", "desc": "index/key into a collection"},
+    "Has Elements": {"family": "data", "desc": "test a collection is non-empty"},
+    "List Keys": {"family": "data", "desc": "list a map's keys"},
+    "Length": {"family": "data", "desc": "length of a string/list"},
+    "Trim": {"family": "data", "desc": "trim whitespace"},
+    "Concatenate": {"family": "data", "desc": "concatenate strings"},
+    "Replace": {"family": "data", "desc": "string replace"},
+    "RegEx Replace": {"family": "data", "desc": "regex replace"},
+    "Add": {"family": "data", "desc": "numeric/string add"},
+    "Call API": {"family": "integration", "desc": "HTTP request (REST)"},
+    "Execute Query": {"family": "integration", "desc": "SQL SELECT"},
+    "Execute Query V1": {"family": "integration", "desc": "SQL SELECT (v1)"},
+    "Execute Query V2": {"family": "integration", "desc": "SQL SELECT (v2)"},
+    "Execute Command": {"family": "integration", "desc": "SQL non-query (INSERT/UPDATE/DELETE)"},
+    "Execute Command V1": {"family": "integration", "desc": "SQL non-query (v1)"},
+    "Send Email": {"family": "integration", "desc": "SMTP email"},
+    "UTC Now": {"family": "datetime", "desc": "current UTC time"},
+    "Today": {"family": "datetime", "desc": "current date"},
+    "Format DateTime": {"family": "datetime", "desc": "format a datetime"},
+    "Update DateTime": {"family": "datetime", "desc": "add/subtract on a datetime"},
+    "Generate GUID": {"family": "datetime", "desc": "new GUID"},
+    "Upload File": {"family": "file", "desc": "upload a file"},
+    "Get File Data": {"family": "file", "desc": "read a file's data"},
+    "Move File v1": {"family": "file", "desc": "move/rename a file"},
+    "Create Folder": {"family": "file", "desc": "create a folder"},
+    "Read Range": {"family": "file", "desc": "read an Excel range"},
+    "Get Last Used Row": {"family": "file", "desc": "last used Excel row"},
+    "Export To XLSX": {"family": "file", "desc": "write rows to an .xlsx"},
+    "Generate Document": {"family": "document", "desc": "render a document template (file or HTML)"}
+  }
+}

procesio_cli/tools/procesio/dto/data/platform_types.json

@@ -0,0 +1,182 @@
+{
+  "_note": "Platform data types (primitive + procesio built-in). Stable ids. Fetched live 2026-06-24 from /api/DataTypes/primary and /api/DataTypes/procesio. Regenerate with dto/data/_refresh.py.",
+  "primary": [
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121210",
+      "name": "Boolean",
+      "displayName": "Boolean",
+      "csharpCorrespondent": 10,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121211",
+      "name": "Integer",
+      "displayName": "Integer",
+      "csharpCorrespondent": 20,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121212",
+      "name": "Float",
+      "displayName": "Float",
+      "csharpCorrespondent": 30,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121213",
+      "name": "Double",
+      "displayName": "Double",
+      "csharpCorrespondent": 40,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121214",
+      "name": "String",
+      "displayName": "String",
+      "csharpCorrespondent": 50,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121218",
+      "name": "DateTime",
+      "displayName": "DateTime",
+      "csharpCorrespondent": 90,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121220",
+      "name": "Json",
+      "displayName": "Json",
+      "csharpCorrespondent": 120,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121221",
+      "name": "Object",
+      "displayName": "Object",
+      "csharpCorrespondent": 140,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121222",
+      "name": "Guid",
+      "displayName": "Guid",
+      "csharpCorrespondent": 100,
+      "isDataModel": false
+    }
+  ],
+  "procesio": [
+    {
+      "id": "10c6ac59-3929-49e6-99dc-121212121219",
+      "name": "FileDataModel",
+      "displayName": "File",
+      "csharpCorrespondent": 0,
+      "isDataModel": true
+    },
+    {
+      "id": "10c6ac59-3929-49e6-99dc-121212121220",
+      "name": "ErrorDataModel",
+      "displayName": "Error",
+      "csharpCorrespondent": 0,
+      "isDataModel": true
+    },
+    {
+      "id": "10c6ac59-3929-49e6-99dc-121212121221",
+      "name": "SystemDataModel",
+      "displayName": "System variable model",
+      "csharpCorrespondent": 0,
+      "isDataModel": true
+    },
+    {
+      "id": "7bd4db6d-42c6-4ee3-bd9e-b906c1d93e23",
+      "name": "inboundEmailInformation",
+      "displayName": "InboundEmailInformation",
+      "csharpCorrespondent": 0,
+      "isDataModel": true
+    },
+    {
+      "id": "62808178-eae9-4916-9ead-c1ba3e4d8281",
+      "name": "correlation",
+      "displayName": "Correlation",
+      "csharpCorrespondent": 0,
+      "isDataModel": true
+    },
+    {
+      "id": "a09d55c4-c26a-40b3-951d-77c3d4fffe18",
+      "name": "FileContent",
+      "displayName": "FileContent",
+      "csharpCorrespondent": 0,
+      "isDataModel": true
+    },
+    {
+      "id": "a09d55c4-c26a-40b3-951d-77c3d4fffe19",
+      "name": "FTPFilesInformations",
+      "displayName": "SFTPFilesInformation",
+      "csharpCorrespondent": 0,
+      "isDataModel": true
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121210",
+      "name": "Boolean",
+      "displayName": "Boolean",
+      "csharpCorrespondent": 10,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121211",
+      "name": "Integer",
+      "displayName": "Integer",
+      "csharpCorrespondent": 20,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121212",
+      "name": "Float",
+      "displayName": "Float",
+      "csharpCorrespondent": 30,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121213",
+      "name": "Double",
+      "displayName": "Double",
+      "csharpCorrespondent": 40,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121214",
+      "name": "String",
+      "displayName": "String",
+      "csharpCorrespondent": 50,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121218",
+      "name": "DateTime",
+      "displayName": "DateTime",
+      "csharpCorrespondent": 90,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121220",
+      "name": "Json",
+      "displayName": "Json",
+      "csharpCorrespondent": 120,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121221",
+      "name": "Object",
+      "displayName": "Object",
+      "csharpCorrespondent": 140,
+      "isDataModel": false
+    },
+    {
+      "id": "0317bfee-b2f5-4bde-bfe8-121212121222",
+      "name": "Guid",
+      "displayName": "Guid",
+      "csharpCorrespondent": 100,
+      "isDataModel": false
+    }
+  ]
+}

procesio_cli/tools/procesio/dto/datatype/builder.py

@@ -0,0 +1,223 @@
+"""Data Model (DataType) builder — PURE config -> CreateDataTypeDto.
+
+Verified against POST /api/DataTypes (the server assigns the real model/attribute
+ids, ignoring ours; it derives each attribute's type from DataTypeId). See
+description.md. Edit is desired-state: PUT renames the model, then attributes are
+reconciled (add new / delete removed / replace changed) via the attribute
+endpoints — DataType edit cannot change attributes in a single PUT.
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+
+from tools.procesio.dto import refdata
+from tools.procesio.dto.framework import Component
+
+DIR = Path(__file__).resolve().parent
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+def _attribute(a: dict, parent_id: str, ctx: dict) -> dict:
+    """Expand one config attribute into a DataAttributeDto. Recursive for inline
+    nested objects."""
+    nid = ctx.get("new_id") or _new_id
+    name = a["name"]
+    disp = a.get("displayName") or name
+    is_list = bool(a.get("isList", False))
+    aid = nid()
+    node = {
+        "Id": aid, "ParentDataTypeId": parent_id, "Name": name, "DisplayName": disp,
+        "DataTypeName": None, "IsPrimaryType": False, "IsProcesio": False,
+        "IsPublic": bool(a.get("isPublic", False)), "Type": 1, "IsList": is_list,
+        "jsonProperty": a.get("jsonProperty") or name, "hidden": bool(a.get("hidden", False)),
+        "Attributes": [],
+    }
+    if "attributes" in a:                       # inline nested object -> sub data model
+        node["DataTypeId"] = nid()
+        node["IsDataModel"] = True
+        node["CsharpCorrespondent"] = 0
+        node["Attributes"] = [_attribute(x, node["Id"], ctx) for x in a["attributes"]]
+    elif "model" in a:                          # reference an existing data model
+        ref = a["model"].strip()
+        node["DataTypeId"] = (ctx.get("models", {}).get(ref.lower()) or ref)
+        node["IsDataModel"] = True
+        node["CsharpCorrespondent"] = 0
+    else:                                       # primitive
+        node["DataTypeId"] = refdata.primitive_type_id(a["type"])
+        node["IsDataModel"] = False
+        node["CsharpCorrespondent"] = refdata.csharp_correspondent(a["type"])
+    return node
+
+
+def build(config: dict, ctx: dict) -> dict:
+    """config -> CreateDataTypeDto (the POST /api/DataTypes body)."""
+    nid = ctx.get("new_id") or _new_id
+    name = config["name"]
+    disp = config.get("displayName") or name
+    public = bool(config.get("isPublic", True))
+    # platform trick: Data Model from JSON — `fromJson` infers the model server-side
+    # (prepare_ctx calls POST /api/DataTypes/generate); we wrap it as the Content.
+    if ctx.get("generated_content"):
+        content = dict(ctx["generated_content"])
+        content.update({"Name": name, "DisplayName": disp, "IsDataModel": True,
+                        "IsPrimaryType": False, "IsProcesio": False, "IsPublic": public,
+                        "CsharpCorrespondent": 0, "Type": 1})
+        return {"Name": name, "DisplayName": disp, "IsPublic": public, "Content": content}
+    model_id = nid()
+    content = {
+        "Id": model_id, "Name": name, "DisplayName": disp,
+        "IsDataModel": True, "IsPrimaryType": False, "IsProcesio": False,
+        "IsPublic": public, "CsharpCorrespondent": 0, "Type": 1, "ParentIds": [],
+        "Attributes": [_attribute(a, model_id, ctx) for a in config.get("attributes", [])],
+    }
+    return {"Name": name, "DisplayName": disp, "IsPublic": public, "Content": content}
+
+
+# -- live id resolution for `model` references (impure, runs in the handler) ----
+
+def prepare_ctx(client, config: dict) -> dict:
+    """Resolve any `model: <name>` references to live data-model ids in the active
+    workspace, so the pure build step can stay offline."""
+    out: dict = {}
+    fj = config.get("fromJson")
+    if fj is not None:                          # Data Model from JSON (platform trick)
+        content = fj if isinstance(fj, str) else json.dumps(fj)
+        gen = client.post("/api/DataTypes/generate",
+                          {"Name": config["name"], "DisplayName": config.get("displayName") or config["name"],
+                           "Content": content})
+        out["generated_content"] = gen
+        return out
+    refs = _collect_model_refs(config)
+    if not refs:
+        return {"models": {}}
+    models: dict[str, str] = {}
+    r = client.get("/api/DataTypes", {"addProperties": False, "pageNumber": 1,
+                                      "pageItemCount": 500, "includeProcesioEntries": True,
+                                      "includeExternalEntries": True})
+    items = r.get("pageItems") if isinstance(r, dict) else r
+    for it in (items or []):
+        nm = (it.get("name") or it.get("Name") or "").strip().lower()
+        if nm:
+            models[nm] = it.get("id") or it.get("Id")
+    return {"models": models}
+
+
+def _collect_model_refs(config: dict) -> set[str]:
+    found: set[str] = set()
+
+    def walk(attrs):
+        for a in attrs or []:
+            if "model" in a:
+                found.add(a["model"].strip().lower())
+            if "attributes" in a:
+                walk(a["attributes"])
+    walk(config.get("attributes", []))
+    # An id reference (a guid) needn't be resolved; only names do, but resolving
+    # all is harmless — the builder falls back to the literal when not found.
+    return found
+
+
+def _add_one_attribute(client, parent_id: str, a: dict) -> None:
+    """Add ONE attribute to a model via POST /api/DataTypes/attribute/{parentId} — the
+    SAME minimal call the PROCESIO UI makes (HAR-verified). For a model-REFERENCE
+    attribute (dataTypeId = another model's id) the server auto-inlines that model's
+    whole attribute tree into the parent AND compiles it. For an inline NEW sub-model
+    (the config used `attributes:`), create the sub-model first (empty + its own
+    attributes) then reference it by id — the UI never inlines a brand-new model in one
+    call. The minimal payload the UI sends: {id, displayName, name, dataTypeId, isList,
+    jsonProperty, parentDataTypeId}; the server derives isDataModel/type/etc."""
+    data_type_id = a.get("DataTypeId")
+    if a.get("IsDataModel") and a.get("Attributes"):   # inline NEW sub-model -> create first
+        sub = client.post("/api/DataTypes", {
+            "name": a.get("Name"), "displayName": a.get("DisplayName") or a.get("Name"),
+            "content": None, "isPublic": True})
+        sub_id = sub.get("id") or sub.get("Id")
+        for child in a.get("Attributes") or []:
+            _add_one_attribute(client, sub_id, child)
+        data_type_id = sub_id
+    payload = {
+        "id": None, "displayName": a.get("DisplayName") or a.get("Name"),
+        "name": a.get("Name"), "dataTypeId": data_type_id,
+        "isList": bool(a.get("IsList")), "jsonProperty": a.get("jsonProperty") or a.get("Name"),
+        "parentDataTypeId": parent_id}
+    if a.get("hidden"):
+        payload["hidden"] = True
+    if a.get("IsPublic"):
+        payload["isPublic"] = True
+    client.post(f"/api/DataTypes/attribute/{parent_id}", payload)
+
+
+def _create(client, dto, ctx):
+    """Create a data model exactly the way the PROCESIO UI does (HAR-verified): POST an
+    EMPTY model (content:null), then add EVERY attribute one-by-one via the attribute
+    endpoint. Attributes placed in the initial POST /api/DataTypes `Content` show up in
+    GET but are NEVER compiled into the runtime model — so documents binding the model
+    render "Unknown" and Generate Document throws "Unable to find attribute <id>". The
+    attribute endpoint is what compiles them (and inlines referenced child models). The
+    Data-Model-from-JSON path (generated_content) keeps the single POST — there the
+    server infers and creates the nested private models itself."""
+    if ctx.get("generated_content"):
+        return client.post("/api/DataTypes", dto)
+    content = (dto.get("Content") if isinstance(dto, dict) else None) or {}
+    resp = client.post("/api/DataTypes", {
+        "name": dto.get("Name"), "displayName": dto.get("DisplayName"),
+        "content": None, "isPublic": dto.get("IsPublic", True)})
+    model_id = (resp.get("id") or resp.get("Id")) if isinstance(resp, dict) else None
+    for a in content.get("Attributes") or []:
+        _add_one_attribute(client, model_id, a)
+    return resp
+
+
+def _extract_id(resp, dto):
+    if isinstance(resp, dict):
+        return resp.get("id") or resp.get("Id")
+    return None
+
+
+# -- desired-state edit: PUT rename + reconcile attributes ---------------------
+
+def _edit(client, resource_id, config: dict, ctx: dict):
+    name = config["name"]
+    disp = config.get("displayName") or name
+    # 1) top-level rename / displayName
+    client.put("/api/DataTypes", {"Id": resource_id, "Name": name, "DisplayName": disp})
+    # 2) reconcile attributes against current
+    current = client.get(f"/api/DataTypes/{resource_id}")
+    cur_attrs = {(a.get("name") or "").lower(): a for a in (current.get("attributes") or [])}
+    want = {a["name"].lower(): a for a in config.get("attributes", [])}
+    # delete removed
+    for nm, a in cur_attrs.items():
+        if nm not in want:
+            client.delete(f"/api/DataTypes/attribute/{resource_id}/{a.get('id')}")
+    # add new / replace changed
+    for nm, a in want.items():
+        built = _attribute(a, resource_id, ctx)
+        if nm not in cur_attrs:
+            _add_one_attribute(client, resource_id, built)  # compiles + inlines model refs
+        else:
+            cur = cur_attrs[nm]
+            same = (cur.get("dataTypeId") == built["DataTypeId"]
+                    and bool(cur.get("isList")) == built["IsList"])
+            if not same:
+                built["Id"] = cur.get("id")
+                client.put(f"/api/DataTypes/attribute/{resource_id}", built)
+    return client.get(f"/api/DataTypes/{resource_id}")
+
+
+COMPONENT = Component(
+    name="datatype",
+    description="PROCESIO data model (DataType): a named set of typed attributes.",
+    dir=DIR,
+    build=build,
+    create_endpoint=("POST", "/api/DataTypes"),
+    create=_create,   # add model-reference attrs via the attribute endpoint -> parentIds back-link
+    get_path="/api/DataTypes/{id}",
+    extract_id=_extract_id,
+    prepare_ctx=prepare_ctx,
+    edit=_edit,
+)

procesio_cli/tools/procesio/dto/datatype/config.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PROCESIO Data Model (DataType) config",
+  "description": "Minimal config to create/edit a PROCESIO custom data model. The builder expands each attribute into a full DataAttributeDto and wraps it in a CreateDataTypeDto. Primitive types resolve to stable platform ids; 'model' references another data model by name or id; 'attributes' defines an inline nested object.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name"],
+  "properties": {
+    "name": {"type": "string", "minLength": 1, "description": "Internal model name (the JSON key/identifier)."},
+    "displayName": {"type": "string", "description": "UI display name; defaults to name."},
+    "isPublic": {"type": "boolean", "default": true, "description": "Whether the model is public in the workspace."},
+    "fromJson": {"description": "Platform trick: infer the whole model from a JSON sample (object or JSON string) via /api/DataTypes/generate. Overrides attributes."},
+    "attributes": {
+      "type": "array",
+      "description": "The model's fields. Empty is allowed (an empty object model). Omit when using fromJson.",
+      "items": {"$ref": "#/$defs/attribute"}
+    }
+  },
+  "$defs": {
+    "attribute": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "displayName": {"type": "string"},
+        "jsonProperty": {"type": "string", "description": "JSON key this field maps to (defaults to name)."},
+        "isList": {"type": "boolean", "default": false, "description": "Field holds a list/array of the type."},
+        "hidden": {"type": "boolean", "default": false, "description": "Hide the attribute in the model UI."},
+        "isPublic": {"type": "boolean", "default": false, "description": "Mark the attribute public."},
+        "type": {
+          "type": "string",
+          "description": "A primitive type. Exactly one of type|model|attributes per attribute.",
+          "enum": ["boolean", "integer", "float", "double", "string", "datetime", "json", "object", "guid",
+                    "bool", "int", "long", "number", "text", "str", "uuid", "date-time"]
+        },
+        "model": {"type": "string", "description": "Reference another data model by name or id (makes this a nested model field)."},
+        "attributes": {"type": "array", "items": {"$ref": "#/$defs/attribute"}, "description": "Inline nested object — its own fields."}
+      },
+      "oneOf": [
+        {"required": ["type"]},
+        {"required": ["model"]},
+        {"required": ["attributes"]}
+      ]
+    }
+  }
+}

procesio_cli/tools/procesio/dto/datatype/description.md

@@ -0,0 +1,85 @@
+# Data Model (DataType) sub-tool
+
+Full lifecycle for a PROCESIO **custom data model** — a named set of typed attributes
+referenced by process variables, documents, webhooks, forms, and data stores.
+
+## Actions
+
+| Action | What |
+|---|---|
+| `datatype-create` | Build a model from a config (attribute-by-attribute, **or** `fromJson`). |
+| `datatype-edit` | Desired-state edit: rename + add/replace/remove attributes. |
+| `datatype-get` | `GET /api/DataTypes/{id}` — model + attributes. |
+| `datatype-delete` | Delete a model. |
+| `datatype-add-attribute` | Add ONE attribute (`--id --name --data-type [--is-list --hidden --public …]`). |
+| `datatype-edit-attribute` | Edit ONE attribute (`--id --attribute` + fields to change). |
+| `datatype-delete-attribute` | Remove ONE attribute. |
+| `datatype-change-to-public` | Promote a **private** inner model (from `fromJson`) to **public**. |
+| `datatype-clone` | Clone an inner model. |
+
+(Raw 1:1 endpoints — `post-datatypes`, `post-datatypes-attribute-by-rootdatatypeid`,
+`post-datatypes-private`, `post-datatypes-generate-file`, etc. — are also auto-exposed.)
+
+## Config (`datatype-create` / `datatype-edit`)
+
+```json
+{
+  "name": "OrderResult", "displayName": "Order Result", "isPublic": true,
+  "attributes": [
+    {"name": "orderId", "type": "guid"},
+    {"name": "total", "type": "double"},
+    {"name": "lines", "type": "string", "isList": true},
+    {"name": "customer", "model": "CustomerModel"},
+    {"name": "items", "model": "OrderLine", "isList": true},
+    {"name": "meta", "attributes": [{"name": "source", "type": "string", "hidden": true}]}
+  ]
+}
+```
+
+Each attribute is exactly one of:
+- **primitive** — `type` ∈ `boolean integer float double string datetime json object guid`
+  (aliases: `bool int long number text str uuid date-time`); `isList:true` for an array.
+- **model reference** — `model`: another data model by **name** (resolved live) or id →
+  a nested-model field (`isList:true` for a list-of-model, e.g. a document repeating table).
+- **inline nested object** — `attributes`: a brand-new sub-model defined inline.
+
+Per-attribute options: `displayName`, `jsonProperty`, `isList`, `hidden`, `isPublic`.
+
+**Data Model from JSON:** instead of `attributes`, pass `"fromJson": {…sample JSON…}`; the
+model (incl. nested objects/lists) is inferred via `/api/DataTypes/generate`.
+
+## How it works on the wire (HAR-verified — this is the load-bearing detail)
+
+**Create = EMPTY model first, then EACH attribute via the attribute endpoint.** The UI (and
+now this tool) does NOT put attributes in the create POST:
+1. `POST /api/DataTypes` body `{name, displayName, content: null, isPublic}` → `{id}`.
+2. For EACH attribute: `POST /api/dataTypes/attribute/{modelId}` body
+   `{id:null, displayName, name, dataTypeId, isList, jsonProperty, parentDataTypeId}`.
+
+A **model-reference** attribute (`dataTypeId` = another model's id) added this way makes the
+server **auto-inline that child's whole attribute tree into the parent AND link the child's
+`parentIds`**, and COMPILE it. Attributes placed in the create POST's `Content` instead show
+up in `GET /api/DataTypes/{id}` but are **NEVER compiled into the runtime model** — a document
+binding the model then renders every cell **"Unknown"** and Generate Document throws *"Unable
+to find attribute <id>"*. (This cost ~10 debugging rounds; see the
+`procesio-datatype-create` memory note.) Inline nested children are created as their own empty
+model first, then referenced.
+
+**Edit:** `PUT /api/DataTypes` renames only (ignores attributes/parentIds); attributes are
+reconciled via `POST` (add — compiles), `PUT /api/dataTypes/attribute/{id}` (full object,
+change), `DELETE /api/dataTypes/attribute/{id}/{attrId}` (remove).
+
+## Public vs private models — REUSABILITY (important)
+
+- **Attribute-by-attribute** (`datatype-create` with `attributes`): a `model:` reference points
+  at an existing model, which **stays reusable** in other models.
+- **`fromJson`**: the inferred nested inner models are created **PRIVATE — they cannot be
+  reused in other data models.** Promote one with `datatype-change-to-public`
+  (`--root-id <root model> --id <inner model>`) to make it reusable; `datatype-clone` clones an
+  inner model. (`POST /api/dataTypes/changeToPublic|clone` body `{rootDataTypeId, dataTypeId}`.)
+
+## Gotchas
+- `IsProcesio`/`IsPrimaryType` true is rejected on update; always false for custom models.
+- Primitive type ids are stable platform constants, bundled in `dto/data/platform_types.json`.
+- `searchName` filters need ≥ 3 chars to take effect (server-side).
+- `--data-type` on attribute actions accepts a primitive name, an existing model name, or a guid.

procesio_cli/tools/procesio/dto/datatype/fixtures/customer.config.json

@@ -0,0 +1,41 @@
+{
+  "name": "Customer",
+  "displayName": "Customer",
+  "isPublic": true,
+  "attributes": [
+    {
+      "name": "id",
+      "type": "guid"
+    },
+    {
+      "name": "name",
+      "type": "string"
+    },
+    {
+      "name": "age",
+      "type": "integer"
+    },
+    {
+      "name": "tags",
+      "type": "string",
+      "isList": true
+    },
+    {
+      "name": "address",
+      "attributes": [
+        {
+          "name": "city",
+          "type": "string"
+        },
+        {
+          "name": "zip",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "name": "owner",
+      "model": "PersonModel"
+    }
+  ]
+}