Document and validate required schema table names for create_connection

The schema argument requires specific TulipaEnergyModel-convention table names
(asset, asset_both, asset_commission, asset_milestone, flow, flow_both,
flow_commission, flow_milestone). Previously this contract was implicit and
callers got cryptic KeyErrors on mismatch.

- Add `_REQUIRED_SCHEMA_TABLES` const and `_validate_schema` validator
- Throw `ArgumentError` with clear message listing missing tables
- Update `create_connection` docstring to document required schema structure
- Update README schema-driven design bullet with required table names
- Add test verifying ArgumentError is thrown for incomplete schemas

Co-authored-by: Claude Code (claude-sonnet-4-6) <noreply@anthropic.com>

Author: abelsiqueira

README.md

@@ -16,7 +16,11 @@ TulipaBuilder.jl provides a graph-based approach to building energy system model
 ## Key Features
 
 - **Graph-based modeling**: Intuitive representation of energy systems as connected assets
-- **Schema-driven design**: Dynamically compatible with different TulipaEnergyModel.jl versions
+- **Schema-driven design**: Dynamically compatible with different TulipaEnergyModel.jl versions.
+  The `schema` argument passed to `create_connection` must be a dict keyed by TulipaEnergyModel
+  table names. The following table names are required: `asset`, `asset_both`, `asset_commission`,
+  `asset_milestone`, `flow`, `flow_both`, `flow_commission`, `flow_milestone`. Each entry maps
+  column names to type/default metadata. `TulipaEnergyModel.schema` satisfies this automatically.
 - **Simplified workflow**: Streamlined process from model creation to optimization
 
 ### Magic transformations

src/create-connection.jl

@@ -1,5 +1,39 @@
 export create_connection
 
+const _REQUIRED_SCHEMA_TABLES = [
+    "asset",
+    "asset_both",
+    "asset_commission",
+    "asset_milestone",
+    "flow",
+    "flow_both",
+    "flow_commission",
+    "flow_milestone",
+]
+
+"""
+    _validate_schema(schema)
+
+Checks that `schema` contains the table names required by [`create_connection`](@ref).
+Throws an `ArgumentError` listing any missing tables if they are absent.
+This function is for internal use only.
+"""
+function _validate_schema(schema)
+    missing_tables = filter(t -> !haskey(schema, t), _REQUIRED_SCHEMA_TABLES)
+    if !isempty(missing_tables)
+        throw(
+            ArgumentError(
+                "The provided schema is missing required table(s): " *
+                join(sort(missing_tables), ", ") *
+                ".\nExpected table names follow TulipaEnergyModel conventions " *
+                "(e.g. asset, asset_both, asset_commission, asset_milestone, " *
+                "flow, flow_both, flow_commission, flow_milestone). " *
+                "Pass TulipaEnergyModel.schema to satisfy this requirement.",
+            ),
+        )
+    end
+end
+
 """
     create_empty_table_from_schema!(connection, table_name, schema, columns)
 
@@ -147,10 +181,25 @@ end
     create_connection(tulipa_data, schema, db)
 
 Creates a DuckDB connection and populates it with the data from `tulipa_data`.
-The `schema` should be a dict in the same format as `TulipaEnergyModel.schema`.
+
+The `schema` must be a `Dict{String, Dict{String, Dict{String, Any}}}` whose
+top-level keys are TulipaEnergyModel table names. The following table names are
+**required**:
+
+  - `"asset"`, `"asset_both"`, `"asset_commission"`, `"asset_milestone"`
+  - `"flow"`, `"flow_both"`, `"flow_commission"`, `"flow_milestone"`
+
+Each table entry maps column names to dicts with at least a `"type"` key and
+an optional `"default"` key. This structure matches `TulipaEnergyModel.schema`
+(derived from `input-schemas.json` in TulipaEnergyModel.jl), which is the
+intended source for this argument.
+
+Throws `ArgumentError` if any required table name is missing from `schema`.
+
 If `db` is not given, a memory connection is created.
 """
 function create_connection(tulipa::TulipaData, schema; db = ":memory:")
+    _validate_schema(schema)
     connection = DBInterface.connect(DuckDB.DB, db)
     run_query(s) = DuckDB.query(connection, s)
 
@@ -468,6 +517,7 @@ function create_connection(tulipa::TulipaData, schema; db = ":memory:")
         # Handle all profiles (stored with 4-tuple key: profile_type, milestone_year, commission_year, scenario)
         for ((profile_type, milestone_year, commission_year, scenario), profile_value) in
             asset.profiles
+
             profile_name = "$asset_name-$profile_type-$commission_year"
 
             # Use DataFrame for efficient bulk insertion
@@ -527,6 +577,7 @@ function create_connection(tulipa::TulipaData, schema; db = ":memory:")
                 (profile_type, milestone_year, commission_year, scenario),
                 profile_value,
             ) in flow.profiles
+
                 profile_name = "$from_asset_name-$to_asset_name-$profile_type-$commission_year"
                 profiles_df = DataFrame(
                     profile_name = profile_name,

test/test-create-connection.jl

@@ -3,6 +3,28 @@
     const MIN_FLOW_TABLES = ["flow", "flow_commission", "flow_milestone"]
 end
 
+@testitem "create_connection throws ArgumentError for missing required schema tables" tags =
+    [:schema, :unit, :fast] setup = [CommonSetup, TestSchema] begin
+    tulipa = TulipaData()
+    add_asset!(tulipa, "producer", :producer)
+
+    # Schema missing all required tables
+    @test_throws ArgumentError create_connection(tulipa, Dict{String,Any}())
+
+    # Schema missing one required table
+    incomplete_schema = copy(TestSchema.schema)
+    delete!(incomplete_schema, "asset_both")
+    @test_throws ArgumentError create_connection(tulipa, incomplete_schema)
+
+    # Error message lists the missing table
+    err = try
+        create_connection(tulipa, incomplete_schema)
+    catch e
+        e
+    end
+    @test occursin("asset_both", err.msg)
+end
+
 @testitem "Create connection after add_asset" tags = [:schema] setup =
     [CommonSetup, CreateConnectionSetup, TestSchema] begin
     tulipa = TulipaData()