SchemaSmith Enterprise Documentation

What Are Script Tokens?

TLDR; Key/Value pairs that allow deferred resolution.

Overview Rules & Usage Token Types Resources
Script Token

Overview

A script token is a key/value pair that you reference using {{..}} delimiters. At runtime, the placeholder is replaced with the corresponding value. This allows you to abstract and defer values until execution time. Script tokens are defined in the ScriptTokens section of either product.json or template.json, and can be used within any SQL script or script property.

System Defined Tokens

Token Name Value
ProductNameAutomatically set to your product's name.
TemplateNameSet to the name of the current template being quenched (available only within the template scope).
TableSchemaA JSON array of all the table JSON objects at the current template level.
SpecificTableLets you reference the JSON of a specific table within the template.
TableSchema_<TemplateName>For each template in the product, this provides access to a metadata structure (useful for shared data dictionaries).

Example: Defining the token ReleaseVersion in your product.json 


{
    "ScriptTokens": {
        "ReleaseVersion": "1.0.0"
    }
}

Can be used in a template: 


{
  "VersionStampScript": "INSERT ProductVersions(Product, Version) VALUES( '{{ProductName}}', '{{ReleaseVersion}}')"
}

Tip

Product level script tokens can be overridden via appSettings or environment variables.

Rules & Usage

  • Script tokens can be defined in product.json and/or template.json.
  • Product level tokens are available across all templates.
  • Template level tokens are scoped only to that template.
  • Tokens can be used in any SQL script property (ie, DatabaseIdentificationScript, VersionStampScript, etc) in both product.json and template.json.
  • They are valid within any SQL script, including migrations, object scripts, and in definitions for table components (like constraints or filters).

Important

If the same token exists at both product and template levels, the token closest to the script context takes precedence. For example, if used in a stored procedure script it resolves from the template; in product validation scripts, it resolves from the product-level definition.

Specific Table Tokens

These tokens allow you to reference the JSON for a specific table in a script-ideal for migration scenarios where you want to avoid duplication.

They are defined like this:


{
    "ScriptTokens": {
        "dbo.MyTable Schema": "<*SpecificTable*>dbo.MyTable"
    }
}

Query Tokens

Query tokens execute an SQL query and store the first column of each result row as lines in a string.

Define one like this:


{
    "ScriptTokens": {
        "DatabaseList": "<*Query*>SELECT [Name] FROM master.dbo.sysdatabases WHERE [Name] IN ('master', 'tempdb') ORDER BY [Name]"
    }
}

The DatabaseList value becomes:


master
tempdb

Important

Formatting must be handled by your SQL. No assumptions are made by the system.

File Tokens

These tokens load file content into the token's value.

  • File tokens <*File*>: Load textual content, such as JSON for data insertion.
  • Binary tokens <*BinaryFile*>: Load binary content, such as a CLR DLL for deployment.

Examples:


{
    "ScriptTokens": {
        "MyTableData": "<*File*>Tables/dbo.MyTable.data",
        "CLRAssembly": "<*BinaryFile*>Files/MyCLR.dll"
    }
}

Use Cases:

  • Load data files directly into SQL (ie, for inserts)
  • Load binary objects like CLR assemblies

Query File Tokens

This hybrid token loads the content of a file, executes it as a query, and uses the results like a query token.

Defined like:


{
    "ScriptTokens": {
        "MyGeneratedCode": "<*QueryFile*>Query Files/Generate select list for latest column definition.sql"
    }
}

Tip

Scripts within Query and QueryFile tokens may themselves include non-query script tokens, which will be resolved prior to execution.

Custom Properties

Table-level custom properties can be referenced within scripts for that table or its components. Use the {{...}} syntax, and prefix property names with Table. to accurately reference the table-level context. You can also reference any properties for the current table component using the same syntax but without the prefix.

Additional Resources

Product Demos - Sample databases converted to the SchemaSmith metadata format. Examples Configuration Settings Reference - Explore the configuration options available in appSettings.json. Reference Product Definition Guide - Structure your metadata into products. Reference Template Creation Tutorial - Create templates for different environments. Reference SchemaHammer - Easily search, edit and preview your script tokens. Related