Change "DB version" language to "DB dir" language

2026-04-17 18:44:23 +00:00 · 2026-03-02 21:57:09 -04:00
parent 346cc75ba9
commit 0b34a5690c
9 changed files with 131 additions and 125 deletions
--- a/README.md
+++ b/README.md
@@ -16,6 +16,11 @@ The primary schema root folder is configurable via:

 - `CPPBESSOT_WORKDIR` (defaults to `db`)

+This repo also carries self-contained schema fixtures for test runs:
+
+- `db/test-schema-v1.1`
+- `db/test-schema-v1.2`
+
 ## Simple Integration Guide

 ### 1) Add the module from your parent project
@@ -25,15 +30,15 @@ The primary schema root folder is configurable via:
 cmake_minimum_required(VERSION 3.16)
 project(MyApp LANGUAGES CXX)

-# Optional: where schema versions live (default is "db")
+# Optional: where schema directories live (default is "db")
 set(CPPBESSOT_WORKDIR "db")

-# Required for generation/library selection
-set(DB_SCHEMA_VERSION_TO_GENERATE "v1.1")
+# Required: exact schema directory basename under CPPBESSOT_WORKDIR
+set(DB_SCHEMA_DIR_TO_GENERATE "v1.1")

 # Optional: only needed if you will run db_gen_migrations
-# set(DB_SCHEMA_MIGRATION_VERSION_FROM "v1.1")
-# set(DB_SCHEMA_MIGRATION_VERSION_TO "v1.2")
+# set(DB_SCHEMA_DIR_MIGRATION_FROM "v1.1")
+# set(DB_SCHEMA_DIR_MIGRATION_TO "v1.2")

 include(path/to/cppbessot/cmake/CppBeSSOT.cmake)
 ```
@@ -51,11 +56,24 @@ Optional migration generation:

 ```bash
 cmake -S . -B build \
-  -DDB_SCHEMA_MIGRATION_VERSION_FROM=v1.1 \
-  -DDB_SCHEMA_MIGRATION_VERSION_TO=v1.2
+  -DDB_SCHEMA_DIR_MIGRATION_FROM=v1.1 \
+  -DDB_SCHEMA_DIR_MIGRATION_TO=v1.2
 cmake --build build --target db_gen_migrations
 ```

+### 2b) Build the bundled serdes tests
+
+These tests validate that checked-in generated C++ model code can be compiled and used for JSON round trips. They are owned by `cppbessot`, not by any parent project.
+
+```bash
+git submodule update --init --recursive tests/googletest
+cmake -S . -B build-tests -DDB_SCHEMA_DIR_TO_GENERATE=test-schema-v1.2
+cmake --build build-tests --target cpp_serdes_test_schema_v1_2
+ctest --test-dir build-tests --output-on-failure
+```
+
+The local test fixtures live under `db/test-schema-v1.1` and `db/test-schema-v1.2`. They intentionally differ so migration generation has real additive schema changes to process.
+
 ### 3) Link generated libraries

 ```cmake
--- a/cmake/CppBeSSOT.cmake
+++ b/cmake/CppBeSSOT.cmake
@@ -15,18 +15,18 @@ if(NOT DEFINED CPPBESSOT_WORKDIR)
  set(CPPBESSOT_WORKDIR "db" CACHE STRING "CppBeSSOT schema root folder")
 endif()

-if(NOT DEFINED DB_SCHEMA_VERSION_TO_GENERATE)
-  set(DB_SCHEMA_VERSION_TO_GENERATE "v1.1" CACHE STRING "Schema version to generate artifacts for")
+if(NOT DEFINED DB_SCHEMA_DIR_TO_GENERATE)
+  set(DB_SCHEMA_DIR_TO_GENERATE "v1.1" CACHE STRING "Schema directory basename under CPPBESSOT_WORKDIR to generate artifacts for")
 endif()

-if(NOT DEFINED DB_SCHEMA_MIGRATION_VERSION_FROM)
-  set(DB_SCHEMA_MIGRATION_VERSION_FROM "" CACHE STRING
-    "Optional source schema version for migration generation (e.g. v1.1)")
+if(NOT DEFINED DB_SCHEMA_DIR_MIGRATION_FROM)
+  set(DB_SCHEMA_DIR_MIGRATION_FROM "" CACHE STRING
+    "Optional source schema directory basename for migration generation")
 endif()

-if(NOT DEFINED DB_SCHEMA_MIGRATION_VERSION_TO)
-  set(DB_SCHEMA_MIGRATION_VERSION_TO "" CACHE STRING
-    "Optional target schema version for migration generation (e.g. v1.2)")
+if(NOT DEFINED DB_SCHEMA_DIR_MIGRATION_TO)
+  set(DB_SCHEMA_DIR_MIGRATION_TO "" CACHE STRING
+    "Optional target schema directory basename for migration generation")
 endif()

 if(NOT DEFINED DB_SCHEMA_CHANGES_ARE_ERROR)
@@ -51,8 +51,8 @@ endfunction()
 function(cppbessot_add_generated_libraries)
  # Purpose: Create consumable libraries from generated model and ODB sources.
  # Inputs:
-  #   - VERSION (optional named arg): Schema version to consume.
-  #   - DB_SCHEMA_VERSION_TO_GENERATE (fallback): Default schema version.
+  #   - SCHEMA_DIR (optional named arg): Schema directory basename to consume.
+  #   - DB_SCHEMA_DIR_TO_GENERATE (fallback): Default schema directory basename.
  # Outputs:
  #   - Library targets (when sources exist):
  #       - cppBeSsotOpenAiModelGen
@@ -64,16 +64,16 @@ function(cppbessot_add_generated_libraries)
  #       - cppbessot::odb_pgsql
  #   - Emits warnings if expected source sets are missing.
  set(options)
-  set(one_value_args VERSION)
+  set(one_value_args SCHEMA_DIR)
  set(multi_value_args)
  cmake_parse_arguments(CPPB "${options}" "${one_value_args}" "${multi_value_args}" ${ARGN})

-  if(NOT CPPB_VERSION)
-    set(CPPB_VERSION "${DB_SCHEMA_VERSION_TO_GENERATE}")
+  if(NOT CPPB_SCHEMA_DIR)
+    set(CPPB_SCHEMA_DIR "${DB_SCHEMA_DIR_TO_GENERATE}")
  endif()

-  cppbessot_validate_schema_version("${CPPB_VERSION}")
-  cppbessot_get_version_dir(_version_dir "${CPPB_VERSION}")
+  cppbessot_validate_schema_dir_name("${CPPB_SCHEMA_DIR}")
+  cppbessot_get_schema_dir_path(_version_dir "${CPPB_SCHEMA_DIR}")

  set(_cpp_include_dir "${_version_dir}/generated-cpp-source/include")
  file(GLOB _model_include_dirs LIST_DIRECTORIES true "${_cpp_include_dir}/*/model")
@@ -89,7 +89,7 @@ function(cppbessot_add_generated_libraries)
    _cppbessot_try_link_nlohmann(cppBeSsotOpenAiModelGen)
    add_library(cppbessot::openai_model_gen ALIAS cppBeSsotOpenAiModelGen)
  else()
-    message(WARNING "No generated C++ model sources found for ${CPPB_VERSION}; skipping libcppBeSsotOpenAiModelGen.")
+    message(WARNING "No generated C++ model sources found for ${CPPB_SCHEMA_DIR}; skipping libcppBeSsotOpenAiModelGen.")
  endif()

  file(GLOB _sqlite_odb_sources CONFIGURE_DEPENDS
@@ -105,7 +105,7 @@ function(cppbessot_add_generated_libraries)
      ${_model_include_dirs})
    add_library(cppbessot::odb_sqlite ALIAS cppBeSsotOdbSqlite)
  else()
-    message(WARNING "No generated sqlite ODB sources found for ${CPPB_VERSION}; skipping libcppBeSsotOdbSqlite.")
+    message(WARNING "No generated sqlite ODB sources found for ${CPPB_SCHEMA_DIR}; skipping libcppBeSsotOdbSqlite.")
  endif()

  file(GLOB _pgsql_odb_sources CONFIGURE_DEPENDS
@@ -121,7 +121,7 @@ function(cppbessot_add_generated_libraries)
      ${_model_include_dirs})
    add_library(cppbessot::odb_pgsql ALIAS cppBeSsotOdbPgSql)
  else()
-    message(WARNING "No generated postgre ODB sources found for ${CPPB_VERSION}; skipping libcppBeSsotOdbPgSql.")
+    message(WARNING "No generated postgre ODB sources found for ${CPPB_SCHEMA_DIR}; skipping libcppBeSsotOdbPgSql.")
  endif()
 endfunction()

@@ -130,9 +130,9 @@ function(cppbessot_enable)
  #          targets, aggregate targets, and generated library registration.
  # Inputs:
  #   - CPPBESSOT_WORKDIR
-  #   - DB_SCHEMA_VERSION_TO_GENERATE
-  #   - DB_SCHEMA_MIGRATION_VERSION_FROM
-  #   - DB_SCHEMA_MIGRATION_VERSION_TO
+  #   - DB_SCHEMA_DIR_TO_GENERATE
+  #   - DB_SCHEMA_DIR_MIGRATION_FROM
+  #   - DB_SCHEMA_DIR_MIGRATION_TO
  #   - DB_SCHEMA_CHANGES_ARE_ERROR (optional behavior control)
  # Outputs:
  #   - Custom targets:
@@ -147,30 +147,30 @@ function(cppbessot_enable)
  #   - Generated library targets for selected schema version.
  cppbessot_initialize_paths()

-  cppbessot_validate_schema_version("${DB_SCHEMA_VERSION_TO_GENERATE}")
-  cppbessot_assert_version_dir_exists("${DB_SCHEMA_VERSION_TO_GENERATE}")
+  cppbessot_validate_schema_dir_name("${DB_SCHEMA_DIR_TO_GENERATE}")
+  cppbessot_assert_schema_dir_exists("${DB_SCHEMA_DIR_TO_GENERATE}")

  cppbessot_check_dependencies()

  cppbessot_add_db_check_schema_changes_target()
-  cppbessot_add_db_gen_ts_target("${DB_SCHEMA_VERSION_TO_GENERATE}")
-  cppbessot_add_db_gen_zod_target("${DB_SCHEMA_VERSION_TO_GENERATE}")
-  cppbessot_add_db_gen_cpp_target("${DB_SCHEMA_VERSION_TO_GENERATE}")
-  cppbessot_add_db_gen_odb_target("${DB_SCHEMA_VERSION_TO_GENERATE}")
-  cppbessot_add_db_gen_sql_ddl_target("${DB_SCHEMA_VERSION_TO_GENERATE}")
-  if(NOT "${DB_SCHEMA_MIGRATION_VERSION_FROM}" STREQUAL ""
-     AND NOT "${DB_SCHEMA_MIGRATION_VERSION_TO}" STREQUAL "")
-    cppbessot_validate_schema_version("${DB_SCHEMA_MIGRATION_VERSION_FROM}")
-    cppbessot_validate_schema_version("${DB_SCHEMA_MIGRATION_VERSION_TO}")
-    cppbessot_assert_version_dir_exists("${DB_SCHEMA_MIGRATION_VERSION_FROM}")
-    cppbessot_assert_version_dir_exists("${DB_SCHEMA_MIGRATION_VERSION_TO}")
+  cppbessot_add_db_gen_ts_target("${DB_SCHEMA_DIR_TO_GENERATE}")
+  cppbessot_add_db_gen_zod_target("${DB_SCHEMA_DIR_TO_GENERATE}")
+  cppbessot_add_db_gen_cpp_target("${DB_SCHEMA_DIR_TO_GENERATE}")
+  cppbessot_add_db_gen_odb_target("${DB_SCHEMA_DIR_TO_GENERATE}")
+  cppbessot_add_db_gen_sql_ddl_target("${DB_SCHEMA_DIR_TO_GENERATE}")
+  if(NOT "${DB_SCHEMA_DIR_MIGRATION_FROM}" STREQUAL ""
+     AND NOT "${DB_SCHEMA_DIR_MIGRATION_TO}" STREQUAL "")
+    cppbessot_validate_schema_dir_name("${DB_SCHEMA_DIR_MIGRATION_FROM}")
+    cppbessot_validate_schema_dir_name("${DB_SCHEMA_DIR_MIGRATION_TO}")
+    cppbessot_assert_schema_dir_exists("${DB_SCHEMA_DIR_MIGRATION_FROM}")
+    cppbessot_assert_schema_dir_exists("${DB_SCHEMA_DIR_MIGRATION_TO}")
    cppbessot_add_db_gen_migrations_target(
-      "${DB_SCHEMA_MIGRATION_VERSION_FROM}"
-      "${DB_SCHEMA_MIGRATION_VERSION_TO}")
+      "${DB_SCHEMA_DIR_MIGRATION_FROM}"
+      "${DB_SCHEMA_DIR_MIGRATION_TO}")
  else()
    add_custom_target(db_gen_migrations
      COMMAND "${CMAKE_COMMAND}" -E echo
-              "Set DB_SCHEMA_MIGRATION_VERSION_FROM and DB_SCHEMA_MIGRATION_VERSION_TO to enable migration generation."
+              "Set DB_SCHEMA_DIR_MIGRATION_FROM and DB_SCHEMA_DIR_MIGRATION_TO to enable migration generation."
      COMMAND "${CMAKE_COMMAND}" -E false
      VERBATIM
    )
@@ -186,7 +186,7 @@ function(cppbessot_enable)
    db_gen_sql_ddl)
  set_target_properties(db_gen_orm_serdes_and_zod PROPERTIES EXCLUDE_FROM_ALL TRUE)

-  cppbessot_add_generated_libraries(VERSION "${DB_SCHEMA_VERSION_TO_GENERATE}")
+  cppbessot_add_generated_libraries(SCHEMA_DIR "${DB_SCHEMA_DIR_TO_GENERATE}")
 endfunction()

 if(CPPBESSOT_AUTO_ENABLE)
--- a/cmake/dbGenCpp.cmake
+++ b/cmake/dbGenCpp.cmake
@@ -3,16 +3,16 @@ include_guard(GLOBAL)
 include("${CMAKE_CURRENT_LIST_DIR}/dbGenerationCommon.cmake")
 set(_CPPBESSOT_DB_GEN_CPP_DIR "${CMAKE_CURRENT_LIST_DIR}")

-function(cppbessot_add_db_gen_cpp_target version)
+function(cppbessot_add_db_gen_cpp_target schema_dir)
  # Purpose: Register C++ model generation target using checked-in templates.
  # Inputs:
-  #   - version: Schema version to generate for.
+  #   - schema_dir: Schema directory basename to generate for.
  #   - CPPBESSOT_NPX_EXECUTABLE: Path to `npx`.
  # Outputs:
  #   - CMake target: `db_gen_cpp_headers` (EXCLUDE_FROM_ALL).
-  #   - Files under `<version>/generated-cpp-source`.
-  cppbessot_validate_schema_version("${version}")
-  cppbessot_get_version_dir(_version_dir "${version}")
+  #   - Files under `<schema_dir>/generated-cpp-source`.
+  cppbessot_validate_schema_dir_name("${schema_dir}")
+  cppbessot_get_schema_dir_path(_version_dir "${schema_dir}")
  if(DEFINED CPPBESSOT_MODULE_ROOT AND NOT "${CPPBESSOT_MODULE_ROOT}" STREQUAL "")
    set(_module_root "${CPPBESSOT_MODULE_ROOT}")
  else()
@@ -33,7 +33,7 @@ function(cppbessot_add_db_gen_cpp_target version)
            -c "${_template_config}"
            -o "${_output_dir}"
            --global-property models
-    COMMENT "Generating C++ model headers/sources for ${version}"
+    COMMENT "Generating C++ model headers/sources for ${schema_dir}"
    VERBATIM
  )

--- a/cmake/dbGenMigrations.cmake
+++ b/cmake/dbGenMigrations.cmake
@@ -3,26 +3,26 @@ include_guard(GLOBAL)
 include("${CMAKE_CURRENT_LIST_DIR}/dbGenerationCommon.cmake")
 set(_CPPBESSOT_DB_GEN_MIGRATIONS_DIR "${CMAKE_CURRENT_LIST_DIR}")

-function(cppbessot_add_db_gen_migrations_target from_version to_version)
-  # Purpose: Register migration SQL generation between two schema versions.
+function(cppbessot_add_db_gen_migrations_target from_schema_dir to_schema_dir)
+  # Purpose: Register migration SQL generation between two schema directories.
  # Inputs:
-  #   - from_version: Source schema version (changelog input side).
-  #   - to_version: Target schema version (header/changelog output side).
+  #   - from_schema_dir: Source schema directory basename.
+  #   - to_schema_dir: Target schema directory basename.
  #   - CPPBESSOT_ODB_EXECUTABLE: Path to `odb` compiler.
  # Outputs:
  #   - CMake target: `db_gen_migrations` (EXCLUDE_FROM_ALL).
  #   - Files under `migrations/<from>-<to>/{sqlite,postgre}`.
-  cppbessot_validate_schema_version("${from_version}")
-  cppbessot_validate_schema_version("${to_version}")
+  cppbessot_validate_schema_dir_name("${from_schema_dir}")
+  cppbessot_validate_schema_dir_name("${to_schema_dir}")

-  if("${from_version}" STREQUAL "${to_version}")
-    message(FATAL_ERROR "Migration `from` and `to` versions must differ.")
+  if("${from_schema_dir}" STREQUAL "${to_schema_dir}")
+    message(FATAL_ERROR "Migration `from` and `to` schema directories must differ.")
  endif()

-  cppbessot_get_version_dir(_from_dir "${from_version}")
-  cppbessot_get_version_dir(_to_dir "${to_version}")
+  cppbessot_get_schema_dir_path(_from_dir "${from_schema_dir}")
+  cppbessot_get_schema_dir_path(_to_dir "${to_schema_dir}")
  cppbessot_abs_path(_workdir "${CPPBESSOT_WORKDIR}")
-  set(_migration_dir "${_workdir}/migrations/${from_version}-${to_version}")
+  set(_migration_dir "${_workdir}/migrations/${from_schema_dir}-${to_schema_dir}")

  add_custom_target(db_gen_migrations
    COMMAND "${CMAKE_COMMAND}"
@@ -31,7 +31,7 @@ function(cppbessot_add_db_gen_migrations_target from_version to_version)
            -DCPPBESSOT_TO_VERSION_DIR=${_to_dir}
            -DCPPBESSOT_MIGRATION_DIR=${_migration_dir}
            -P "${_CPPBESSOT_DB_GEN_MIGRATIONS_DIR}/scripts/run_odb_migrations.cmake"
-    COMMENT "Generating DB migrations: ${from_version} -> ${to_version}"
+    COMMENT "Generating DB migrations: ${from_schema_dir} -> ${to_schema_dir}"
    VERBATIM
  )

--- a/cmake/dbGenODB.cmake
+++ b/cmake/dbGenODB.cmake
@@ -3,16 +3,16 @@ include_guard(GLOBAL)
 include("${CMAKE_CURRENT_LIST_DIR}/dbGenerationCommon.cmake")
 set(_CPPBESSOT_DB_GEN_ODB_DIR "${CMAKE_CURRENT_LIST_DIR}")

-function(cppbessot_add_db_gen_odb_target version)
+function(cppbessot_add_db_gen_odb_target schema_dir)
  # Purpose: Register ODB ORM generation target for sqlite and postgre backends.
  # Inputs:
-  #   - version: Schema version to generate for.
+  #   - schema_dir: Schema directory basename to generate for.
  #   - CPPBESSOT_ODB_EXECUTABLE: Path to `odb` compiler.
  # Outputs:
  #   - CMake target: `db_gen_odb_logic` (EXCLUDE_FROM_ALL).
-  #   - Files under `<version>/generated-odb-source/{sqlite,postgre}`.
-  cppbessot_validate_schema_version("${version}")
-  cppbessot_get_version_dir(_version_dir "${version}")
+  #   - Files under `<schema_dir>/generated-odb-source/{sqlite,postgre}`.
+  cppbessot_validate_schema_dir_name("${schema_dir}")
+  cppbessot_get_schema_dir_path(_version_dir "${schema_dir}")

  add_custom_target(db_gen_odb_logic
    COMMAND "${CMAKE_COMMAND}"
@@ -20,7 +20,7 @@ function(cppbessot_add_db_gen_odb_target version)
            -DCPPBESSOT_VERSION_DIR=${_version_dir}
            -P "${_CPPBESSOT_DB_GEN_ODB_DIR}/scripts/run_odb_logic.cmake"
    DEPENDS db_gen_cpp_headers
-    COMMENT "Generating ODB ORM sources for ${version} (sqlite + postgre)"
+    COMMENT "Generating ODB ORM sources for ${schema_dir} (sqlite + postgre)"
    VERBATIM
  )

--- a/cmake/dbGenSqlDDL.cmake
+++ b/cmake/dbGenSqlDDL.cmake
@@ -3,16 +3,16 @@ include_guard(GLOBAL)
 include("${CMAKE_CURRENT_LIST_DIR}/dbGenerationCommon.cmake")
 set(_CPPBESSOT_DB_GEN_SQL_DDL_DIR "${CMAKE_CURRENT_LIST_DIR}")

-function(cppbessot_add_db_gen_sql_ddl_target version)
+function(cppbessot_add_db_gen_sql_ddl_target schema_dir)
  # Purpose: Register SQL DDL snapshot generation target for supported backends.
  # Inputs:
-  #   - version: Schema version to generate for.
+  #   - schema_dir: Schema directory basename to generate for.
  #   - CPPBESSOT_ODB_EXECUTABLE: Path to `odb` compiler.
  # Outputs:
  #   - CMake target: `db_gen_sql_ddl` (EXCLUDE_FROM_ALL).
-  #   - Files under `<version>/generated-sql-ddl/{sqlite,postgre}`.
-  cppbessot_validate_schema_version("${version}")
-  cppbessot_get_version_dir(_version_dir "${version}")
+  #   - Files under `<schema_dir>/generated-sql-ddl/{sqlite,postgre}`.
+  cppbessot_validate_schema_dir_name("${schema_dir}")
+  cppbessot_get_schema_dir_path(_version_dir "${schema_dir}")

  add_custom_target(db_gen_sql_ddl
    COMMAND "${CMAKE_COMMAND}"
@@ -20,7 +20,7 @@ function(cppbessot_add_db_gen_sql_ddl_target version)
            -DCPPBESSOT_VERSION_DIR=${_version_dir}
            -P "${_CPPBESSOT_DB_GEN_SQL_DDL_DIR}/scripts/run_odb_sql_ddl.cmake"
    DEPENDS db_gen_cpp_headers
-    COMMENT "Generating SQL DDL snapshots for ${version} (sqlite + postgre)"
+    COMMENT "Generating SQL DDL snapshots for ${schema_dir} (sqlite + postgre)"
    VERBATIM
  )

--- a/cmake/dbGenTS.cmake
+++ b/cmake/dbGenTS.cmake
@@ -2,16 +2,16 @@ include_guard(GLOBAL)

 include("${CMAKE_CURRENT_LIST_DIR}/dbGenerationCommon.cmake")

-function(cppbessot_add_db_gen_ts_target version)
+function(cppbessot_add_db_gen_ts_target schema_dir)
  # Purpose: Register TypeScript type generation target from OpenAPI input.
  # Inputs:
-  #   - version: Schema version to generate for.
+  #   - schema_dir: Schema directory basename to generate for.
  #   - CPPBESSOT_NPX_EXECUTABLE: Path to `npx`.
  # Outputs:
  #   - CMake target: `db_gen_ts` (EXCLUDE_FROM_ALL).
-  #   - Files under `<version>/generated-ts-types`.
-  cppbessot_validate_schema_version("${version}")
-  cppbessot_get_version_dir(_version_dir "${version}")
+  #   - Files under `<schema_dir>/generated-ts-types`.
+  cppbessot_validate_schema_dir_name("${schema_dir}")
+  cppbessot_get_schema_dir_path(_version_dir "${schema_dir}")

  set(_openapi_file "${_version_dir}/openapi/openapi.yaml")
  set(_output_dir "${_version_dir}/generated-ts-types")
@@ -22,7 +22,7 @@ function(cppbessot_add_db_gen_ts_target version)
            -i "${_openapi_file}"
            -g typescript-fetch
            -o "${_output_dir}"
-    COMMENT "Generating TypeScript types for ${version}"
+    COMMENT "Generating TypeScript types for ${schema_dir}"
    VERBATIM
  )

--- a/cmake/dbGenZod.cmake
+++ b/cmake/dbGenZod.cmake
@@ -2,16 +2,16 @@ include_guard(GLOBAL)

 include("${CMAKE_CURRENT_LIST_DIR}/dbGenerationCommon.cmake")

-function(cppbessot_add_db_gen_zod_target version)
+function(cppbessot_add_db_gen_zod_target schema_dir)
  # Purpose: Register Zod schema generation target from OpenAPI input.
  # Inputs:
-  #   - version: Schema version to generate for.
+  #   - schema_dir: Schema directory basename to generate for.
  #   - CPPBESSOT_NPX_EXECUTABLE: Path to `npx`.
  # Outputs:
  #   - CMake target: `db_gen_zod` (EXCLUDE_FROM_ALL).
-  #   - File `<version>/generated-zod/schemas.ts`.
-  cppbessot_validate_schema_version("${version}")
-  cppbessot_get_version_dir(_version_dir "${version}")
+  #   - File `<schema_dir>/generated-zod/schemas.ts`.
+  cppbessot_validate_schema_dir_name("${schema_dir}")
+  cppbessot_get_schema_dir_path(_version_dir "${schema_dir}")

  set(_openapi_file "${_version_dir}/openapi/openapi.yaml")
  set(_output_dir "${_version_dir}/generated-zod")
@@ -27,7 +27,7 @@ function(cppbessot_add_db_gen_zod_target version)
    COMMAND ${CMAKE_COMMAND}
            -DCPPBESSOT_TARGET_FILE="${_output_file}"
            -P "${_prepend_notice_script}"
-    COMMENT "Generating Zod schemas for ${version}"
+    COMMENT "Generating Zod schemas for ${schema_dir}"
    VERBATIM
  )

--- a/cmake/dbGenerationCommon.cmake
+++ b/cmake/dbGenerationCommon.cmake
@@ -52,65 +52,53 @@ function(cppbessot_require_var var_name)
  endif()
 endfunction()

-function(cppbessot_validate_schema_version version)
-  # Purpose: Validate schema version format and enforce major >= 1.
+function(cppbessot_validate_schema_dir_name schema_dir)
+  # Purpose: Validate that a schema directory selector is a basename, not a path.
  # Inputs:
-  #   - version: Expected format `v<major>.<minor>` (e.g. v1.1).
+  #   - schema_dir: Directory basename under CPPBESSOT_WORKDIR.
  # Outputs:
  #   - No return value; raises FATAL_ERROR if format is invalid.
-  if(NOT "${version}" MATCHES "^v([1-9][0-9]*)\\.([0-9]+)$")
+  if("${schema_dir}" STREQUAL "")
+    message(FATAL_ERROR "Schema directory name must not be empty.")
+  endif()
+
+  if("${schema_dir}" MATCHES "[/\\\\]")
    message(FATAL_ERROR
-      "Invalid schema version `${version}`. Expected format `v<major>.<minor>` with major >= 1 (e.g. v1.1, v1.2).")
+      "Schema directory name `${schema_dir}` must be a basename under CPPBESSOT_WORKDIR, not a path.")
  endif()
 endfunction()

-function(cppbessot_get_version_parts version out_major out_minor)
-  # Purpose: Parse schema version string into numeric major/minor components.
-  # Inputs:
-  #   - version: Schema version string.
-  #   - out_major: Parent-scope variable name for major part.
-  #   - out_minor: Parent-scope variable name for minor part.
-  # Outputs:
-  #   - <out_major> (PARENT_SCOPE): Major component.
-  #   - <out_minor> (PARENT_SCOPE): Minor component.
-  cppbessot_validate_schema_version("${version}")
-  string(REGEX REPLACE "^v([1-9][0-9]*)\\.([0-9]+)$" "\\1" _major "${version}")
-  string(REGEX REPLACE "^v([1-9][0-9]*)\\.([0-9]+)$" "\\2" _minor "${version}")
-  set(${out_major} "${_major}" PARENT_SCOPE)
-  set(${out_minor} "${_minor}" PARENT_SCOPE)
-endfunction()
-
-function(cppbessot_get_version_dir out_var version)
-  # Purpose: Resolve the absolute folder path for a specific schema version.
+function(cppbessot_get_schema_dir_path out_var schema_dir)
+  # Purpose: Resolve the absolute folder path for a specific schema directory.
  # Inputs:
  #   - out_var: Parent-scope variable name to receive the path.
-  #   - version: Schema version string.
+  #   - schema_dir: Schema directory basename under CPPBESSOT_WORKDIR.
  # Outputs:
-  #   - <out_var> (PARENT_SCOPE): Absolute `${CPPBESSOT_WORKDIR}/<version>` path.
-  cppbessot_validate_schema_version("${version}")
+  #   - <out_var> (PARENT_SCOPE): Absolute `${CPPBESSOT_WORKDIR}/<schema_dir>` path.
+  cppbessot_validate_schema_dir_name("${schema_dir}")
  cppbessot_abs_path(_workdir "${CPPBESSOT_WORKDIR}")
-  set(${out_var} "${_workdir}/${version}" PARENT_SCOPE)
+  set(${out_var} "${_workdir}/${schema_dir}" PARENT_SCOPE)
 endfunction()

-function(cppbessot_assert_version_dir_exists version)
-  # Purpose: Assert that a schema version directory exists on disk.
+function(cppbessot_assert_schema_dir_exists schema_dir)
+  # Purpose: Assert that a schema directory exists on disk.
  # Inputs:
-  #   - version: Schema version string.
+  #   - schema_dir: Schema directory basename.
  # Outputs:
  #   - No return value; raises FATAL_ERROR if directory is missing.
-  cppbessot_get_version_dir(_version_dir "${version}")
-  if(NOT IS_DIRECTORY "${_version_dir}")
-    message(FATAL_ERROR "Schema version folder does not exist: ${_version_dir}")
+  cppbessot_get_schema_dir_path(_schema_dir_path "${schema_dir}")
+  if(NOT IS_DIRECTORY "${_schema_dir_path}")
+    message(FATAL_ERROR "Schema directory does not exist: ${_schema_dir_path}")
  endif()
 endfunction()

-function(cppbessot_get_model_headers_glob out_var version)
-  # Purpose: Build a model-header glob expression for a schema version.
+function(cppbessot_get_model_headers_glob out_var schema_dir)
+  # Purpose: Build a model-header glob expression for a schema directory.
  # Inputs:
  #   - out_var: Parent-scope variable name to receive the glob pattern.
-  #   - version: Schema version string.
+  #   - schema_dir: Schema directory basename.
  # Outputs:
  #   - <out_var> (PARENT_SCOPE): Glob pattern for generated model headers.
-  cppbessot_get_version_dir(_version_dir "${version}")
-  set(${out_var} "${_version_dir}/generated-cpp-source/include/*/model/*.h" PARENT_SCOPE)
+  cppbessot_get_schema_dir_path(_schema_dir_path "${schema_dir}")
+  set(${out_var} "${_schema_dir_path}/generated-cpp-source/include/*/model/*.h" PARENT_SCOPE)
 endfunction()