Template Validation
This skill helps validate custom dotnet new templates for correctness before publishing. It encodes the validation rules that catch common authoring mistakes — issues that cause templates to silently fail, produce broken projects, or not appear in dotnet new list.
When to Use
- User asks to check or validate a template.json file
- User reports "my template doesn't show up after installing"
- User wants to review a template before packaging and publishing to NuGet
- User encounters unexpected behavior from a custom template
When Not to Use
- User wants to find or use existing templates — route to
template-discovery
- User wants to create a project — route to
template-instantiation
- User wants to create a template from an existing project — route to
template-authoring
Inputs
| Input |
Required |
Description |
| template.json path |
Yes |
Path to the template.json file or the template directory containing .template.config/template.json |
Validation Rules
When reviewing a template.json, check ALL of the following categories systematically. Report every finding as an error, warning, or suggestion.
1. Required Fields
| Field |
Severity |
Rule |
identity |
ERROR |
Must be present and non-empty |
name |
ERROR |
Must be present and non-empty |
shortName |
ERROR |
Must be present and non-empty |
sourceName |
WARNING |
Without it, --name won't customize the generated project name |
author |
WARNING |
Improves template discoverability |
description |
SUGGESTION |
Helps users understand what the template creates |
classifications |
SUGGESTION |
Improves search and categorization (e.g., ["Web", "API"]) |
defaultName |
SUGGESTION |
Provides a fallback project name when --name is not specified |
2. Identity Format
- ERROR if identity contains spaces — use dots or dashes (e.g.,
MyCompany.WebApi.CSharp)
- WARNING if identity has no namespace separator (
. or -) — use reverse-DNS format
3. ShortName Conflicts
A shortName that matches a dotnet new subcommand conflicts, because dotnet new <name> is then parsed as that subcommand instead of instantiating the template. Read the reserved set for the installed SDK from the Commands: section of dotnet new --help — that is the authoritative source and avoids this rule going stale.
As of current SDKs the subcommands include (illustrative only — version-dependent, do not hardcode this list; the live dotnet new --help output is canonical): install, uninstall, update, list, search, details, create. Note that top-level dotnet verbs like build, run, test, and publish do NOT conflict — dotnet new test does not collide with dotnet test.
- ERROR if shortName matches any subcommand reported by
dotnet new --help (case-insensitive)
- WARNING if shortName is only 1 character — too short for discoverability
- Note: shortName can be a string or an array of strings; check all values
4. Symbol Validation
For each symbol in the symbols object:
- ERROR if a symbol is missing the
type field
- For
type: "parameter":
- WARNING if no
datatype specified (defaults to string)
- SUGGESTION if no
description (improves --help output)
- If
datatype: "choice":
- ERROR if no
choices defined
- ERROR if
choices is empty
- ERROR if
defaultValue is not in the choices list
- WARNING if optional (not
isRequired) and no defaultValue — users get unexpected behavior
- If
datatype: "bool":
- ERROR if
defaultValue is not a valid boolean
- If
datatype: "int":
- ERROR if
defaultValue is not a valid integer
- Valid datatypes:
string, bool, choice, int, float, hex, text
- ERROR if datatype is not in the valid list
- For
type: "computed":
- ERROR if missing
value expression
- For
type: "generated":
- ERROR if missing
generator field
- Valid generators:
casing, coalesce, constant, port, guid, now, random, regex, regexMatch, switch, join
Parameter prefix collisions: WARNING if any parameter name is a prefix of another parameter name (e.g., Auth and AuthMode) — this creates ambiguous parsing in expression contexts.
5. Sources Validation
For source modifier conditions:
- WARNING if a condition string doesn't contain parentheses around symbol names — expected format is
(symbolName), not bare symbolName
6. Post-Action Validation
For each post-action:
- ERROR if missing
actionId
- WARNING if missing
description — this text is shown to users when the action requires manual steps
- SUGGESTION if missing
manualInstructions — these are shown when the action can't run automatically (e.g., in an IDE)
7. Constraint Validation
For each constraint:
- ERROR if missing
type field
- WARNING if missing
args — most constraint types require arguments
8. Tags Validation
- SUGGESTION if no
language tag — adding tags.language (e.g., "C#") improves filtering in dotnet new list --language
- SUGGESTION if no
type tag — adding tags.type (e.g., "project" or "item") improves categorization
Workflow
Step 1: Locate the template.json
The file can be at:
- Direct path:
path/to/template.json
- In a template directory:
path/to/.template.config/template.json
- In a
.template.config directory: path/.template.config/template.json
Step 2: Parse and validate
Read the JSON. If it's malformed, report the JSON parse error with line number.
Run all 8 validation categories above. Collect errors, warnings, and suggestions separately.
Step 3: Report results
Present findings organized by severity:
- Errors (must fix) — template will not work correctly
- Warnings (should fix) — template may cause confusion or limited functionality
- Suggestions (nice to have) — improvements for discoverability and user experience
Include the total: "X error(s), Y warning(s), Z suggestion(s)"
Common Pitfalls
| Pitfall |
Impact |
| ShortName = "list" or "search" |
Template can never be created — conflicts with a dotnet new subcommand |
Missing sourceName |
--name MyProject doesn't rename anything in the generated files |
Choice parameter without defaultValue |
Confusing user experience on optional choice params |
Invalid datatype value |
Template engine ignores the symbol, causing silent failures |
Computed symbol without value |
Template engine throws at instantiation time |
Parameter prefix collision (Auth vs AuthMode) |
Ambiguous expression evaluation |
| Source condition without parentheses |
Condition may not evaluate correctly |
More Info
1---2name: template-validation3description: >4 Validates custom dotnet new templates for correctness before publishing.5 Catches missing fields, parameter bugs, shortName conflicts, constraint issues,6 and common authoring mistakes that cause templates to fail silently.7 USE FOR: checking template.json files for errors before publishing or testing,8 diagnosing why a template doesn't appear after installation, reviewing template9 parameter definitions for type mismatches and missing defaults, finding shortName10 conflicts with dotnet CLI commands, validating post-action and constraint configuration.11 DO NOT USE FOR: finding or using existing templates (use template-discovery),12 creating projects from templates (use template-instantiation), creating templates13 from existing projects (use template-authoring).14license: MIT15metadata:16 source: https://skillmd.com/skills/dotnet/template-validation17---1819# Template Validation2021This skill helps validate custom `dotnet new` templates for correctness before publishing. It encodes the validation rules that catch common authoring mistakes — issues that cause templates to silently fail, produce broken projects, or not appear in `dotnet new list`.2223## When to Use2425- User asks to check or validate a template.json file26- User reports "my template doesn't show up after installing"27- User wants to review a template before packaging and publishing to NuGet28- User encounters unexpected behavior from a custom template2930## When Not to Use3132- User wants to find or use existing templates — route to `template-discovery`33- User wants to create a project — route to `template-instantiation`34- User wants to create a template from an existing project — route to `template-authoring`3536## Inputs3738| Input | Required | Description |39|-------|----------|-------------|40| template.json path | Yes | Path to the template.json file or the template directory containing `.template.config/template.json` |4142## Validation Rules4344When reviewing a template.json, check ALL of the following categories systematically. Report every finding as an error, warning, or suggestion.4546### 1. Required Fields4748| Field | Severity | Rule |49|-------|----------|------|50| `identity` | ERROR | Must be present and non-empty |51| `name` | ERROR | Must be present and non-empty |52| `shortName` | ERROR | Must be present and non-empty |53| `sourceName` | WARNING | Without it, `--name` won't customize the generated project name |54| `author` | WARNING | Improves template discoverability |55| `description` | SUGGESTION | Helps users understand what the template creates |56| `classifications` | SUGGESTION | Improves search and categorization (e.g., `["Web", "API"]`) |57| `defaultName` | SUGGESTION | Provides a fallback project name when `--name` is not specified |5859### 2. Identity Format6061- ERROR if identity contains spaces — use dots or dashes (e.g., `MyCompany.WebApi.CSharp`)62- WARNING if identity has no namespace separator (`.` or `-`) — use reverse-DNS format6364### 3. ShortName Conflicts6566A shortName that matches a `dotnet new` subcommand conflicts, because `dotnet new <name>` is then parsed as that subcommand instead of instantiating the template. Read the reserved set for the installed SDK from the `Commands:` section of `dotnet new --help` — that is the authoritative source and avoids this rule going stale.6768As of current SDKs the subcommands include (illustrative only — version-dependent, do not hardcode this list; the live `dotnet new --help` output is canonical): `install`, `uninstall`, `update`, `list`, `search`, `details`, `create`. Note that top-level `dotnet` verbs like `build`, `run`, `test`, and `publish` do NOT conflict — `dotnet new test` does not collide with `dotnet test`.6970- ERROR if shortName matches any subcommand reported by `dotnet new --help` (case-insensitive)71- WARNING if shortName is only 1 character — too short for discoverability72- Note: shortName can be a string or an array of strings; check all values7374### 4. Symbol Validation7576For each symbol in the `symbols` object:7778- ERROR if a symbol is missing the `type` field79- For `type: "parameter"`:80 - WARNING if no `datatype` specified (defaults to `string`)81 - SUGGESTION if no `description` (improves `--help` output)82 - If `datatype: "choice"`:83 - ERROR if no `choices` defined84 - ERROR if `choices` is empty85 - ERROR if `defaultValue` is not in the choices list86 - WARNING if optional (not `isRequired`) and no `defaultValue` — users get unexpected behavior87 - If `datatype: "bool"`:88 - ERROR if `defaultValue` is not a valid boolean89 - If `datatype: "int"`:90 - ERROR if `defaultValue` is not a valid integer91 - Valid datatypes: `string`, `bool`, `choice`, `int`, `float`, `hex`, `text`92 - ERROR if datatype is not in the valid list93- For `type: "computed"`:94 - ERROR if missing `value` expression95- For `type: "generated"`:96 - ERROR if missing `generator` field97 - Valid generators: `casing`, `coalesce`, `constant`, `port`, `guid`, `now`, `random`, `regex`, `regexMatch`, `switch`, `join`9899**Parameter prefix collisions**: WARNING if any parameter name is a prefix of another parameter name (e.g., `Auth` and `AuthMode`) — this creates ambiguous parsing in expression contexts.100101### 5. Sources Validation102103For source modifier conditions:104- WARNING if a condition string doesn't contain parentheses around symbol names — expected format is `(symbolName)`, not bare `symbolName`105106### 6. Post-Action Validation107108For each post-action:109- ERROR if missing `actionId`110- WARNING if missing `description` — this text is shown to users when the action requires manual steps111- SUGGESTION if missing `manualInstructions` — these are shown when the action can't run automatically (e.g., in an IDE)112113### 7. Constraint Validation114115For each constraint:116- ERROR if missing `type` field117- WARNING if missing `args` — most constraint types require arguments118119### 8. Tags Validation120121- SUGGESTION if no `language` tag — adding `tags.language` (e.g., `"C#"`) improves filtering in `dotnet new list --language`122- SUGGESTION if no `type` tag — adding `tags.type` (e.g., `"project"` or `"item"`) improves categorization123124## Workflow125126### Step 1: Locate the template.json127128The file can be at:129- Direct path: `path/to/template.json`130- In a template directory: `path/to/.template.config/template.json`131- In a `.template.config` directory: `path/.template.config/template.json`132133### Step 2: Parse and validate134135Read the JSON. If it's malformed, report the JSON parse error with line number.136137Run all 8 validation categories above. Collect errors, warnings, and suggestions separately.138139### Step 3: Report results140141Present findings organized by severity:1421. **Errors** (must fix) — template will not work correctly1432. **Warnings** (should fix) — template may cause confusion or limited functionality1443. **Suggestions** (nice to have) — improvements for discoverability and user experience145146Include the total: "X error(s), Y warning(s), Z suggestion(s)"147148## Common Pitfalls149150| Pitfall | Impact |151|---------|--------|152| ShortName = "list" or "search" | Template can never be created — conflicts with a `dotnet new` subcommand |153| Missing `sourceName` | `--name MyProject` doesn't rename anything in the generated files |154| Choice parameter without `defaultValue` | Confusing user experience on optional choice params |155| Invalid `datatype` value | Template engine ignores the symbol, causing silent failures |156| Computed symbol without `value` | Template engine throws at instantiation time |157| Parameter prefix collision (`Auth` vs `AuthMode`) | Ambiguous expression evaluation |158| Source condition without parentheses | Condition may not evaluate correctly |159160## More Info161162- [template.json reference](https://github.com/dotnet/templating/wiki/Reference-for-template.json) — full schema163- [Available Symbol Generators](https://github.com/dotnet/templating/wiki/Available-Symbols-Generators) — generator types164- [Post-action registry](https://github.com/dotnet/templating/wiki/Post-Action-Registry) — action IDs165- [Constraints](https://github.com/dotnet/templating/wiki/Constraints) — constraint types