SchemaSmith Documentation

Schema Packages

The on-disk representation of a database schema definition. Every tool in the suite reads, writes, or modifies schema packages.

Overview Complete Folder Structure .json-schemas Folder ZIP Package Support Filesystem-Illegal Encoding
Schema Packages

A schema package is your database's source of truth — the complete, version-controlled definition of what your databases should look like.

Overview

A schema package is the on-disk artifact that every SchemaSmith tool produces or consumes. It is a folder — or a .zip archive of that folder — holding the product and template configuration, the table definitions, the SQL scripts, and the JSON Schemas that validate every file in the package. One package, one deployable unit, one source of truth.

The package's contents are described elsewhere in the documentation: see Products and templates for the JSON configuration files at the package's core, Defining tables for the table JSON format, and Data delivery alongside Conditional application for the declarative data and deployment controls table files can carry. This page focuses on the package as a container: where files live, how the folder tree is laid out, how ZIP distribution works, and how filesystem-illegal object names get encoded onto disk.

Complete Folder Structure

A schema package is a predictable directory tree. Every tool in the SchemaSmith toolset discovers what it needs by convention — Product.json at the root, Templates/ one level down, platform-specific script folders inside each template — so you never have to configure paths or point a tool at individual files. Marker files and generated artifacts sit alongside the files you author, and the whole layout maps cleanly onto source control. 

MyProduct/
  Product.json                      Product configuration (required)
  .json-schemas/                    JSON Schema files for IDE validation (generated)
    products.schema
    templates.schema
    tables.schema
    indexedviews.schema             SQL Server packages
    materializedviews.schema        PostgreSQL packages
  .community                        Marker file (generated by SchemaTongs)
  Before Product/                   SQL scripts run before all templates
  After Product/                    SQL scripts run after all templates
  Templates/
    TemplateName/
      Template.json                 Template configuration (required)
      Tables/                       Table definition JSON files (all platforms)
        public.customer.json
        sales.order.json
      Indexed Views/                Indexed view definitions (SQL Server only)
        dbo.vw_OrderSummary.json
      Materialized Views/           Materialized view definitions (PostgreSQL only)
        public.mv_active_orders.json
      <platform default folders>    See Default Folders on Products and Templates
      <custom folders>              Anything you declared in ScriptFolders

Table JSON files are named schema.tablename.json (e.g., dbo.Customer.json, public.order_lines.json). For MySQL the schema segment is the database/schema name. If a table or schema name contains filesystem-illegal characters, the encoded form is used in the filename — see Filesystem-Illegal Character Encoding.

SQL script files can be organized into subdirectories within any script folder. All .sql files are discovered recursively and sorted alphabetically by full path.

.json-schemas Folder

Your IDE can help you write correct JSON if you point it at the right schemas. The .json-schemas/ directory at the package root contains JSON Schema definition files generated automatically by SchemaTongs on the fly from the live C# domain types — no embedded files, no shipped artifacts, just a snapshot of the engine's exact current shape.

Per-platform packages get the relevant schemas:

File Validates
products.schema Product.json
templates.schema Template.json
tables.schema Table JSON files (Tables/*.json)
indexedviews.schema Indexed view JSON files (SQL Server packages)
materializedviews.schema Materialized view JSON files (PostgreSQL packages)

Because the schemas are regenerated every time SchemaTongs writes a package, they always match the current engine. If you've hand-edited any of them to add a custom validation fragment under Extensions, that fragment is preserved through regeneration — see Custom Properties: JSON Schema Validation.

ZIP Package Support

SchemaQuench can consume schema packages as ZIP archives. When the SchemaPackagePath configuration value points to a .zip file, SchemaQuench reads the package directly from the archive without extracting it to disk first.

Requirements:

  • The ZIP must contain the standard schema package folder structure.
  • The Product.json file must be at the root of the archive (not nested inside an extra directory).
  • All relative paths within the package must match the standard layout described in Complete Folder Structure.

This is useful for deployment pipelines where the schema package is built as a single artifact.

Filesystem-Illegal Character Encoding

Object names can contain characters that are illegal in file paths on Windows, macOS, or Linux. SchemaTongs uses a percent-encoding scheme to safely map these names to filenames.

Character Encoded As
\%5C
/%2F
:%3A
*%2A
?%3F
"%22
<%3C
>%3E
|%7C
%%25

Additional rules:

  • Leading spaces and dots are encoded (%20 for space, %2E for dot) because many filesystems strip or reject them at the start of filenames.
  • Trailing spaces and dots are similarly encoded.
  • Reserved Windows device names (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9) have their first character percent-encoded.

SchemaQuench decodes these filenames transparently when reading definitions. You generally don't need to worry about encoding unless you're creating JSON files by hand for tables with unusual names.

Last reviewed May 2026 by the SchemaSmith Team.