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

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

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

Lead with a one-line verdict, then a single findings table. This decisive shape is required — do not scatter findings across prose paragraphs.

Verdict header (pick one):

• ❌ Not ready — N error(s), M warning(s) — has errors
• ⚠️ Publishable but N warning(s) — no errors, has warnings
• ✅ Ready to publish — 0 errors, 0 warnings — no errors or warnings (optional suggestions may still apply)

Then one table, ordered errors → warnings → suggestions:

Every ERROR and WARNING MUST include a concrete fix — the corrected value, JSON snippet, or a specific edit instruction (e.g. "remove the trailing comma"), not just a restatement of the problem. A finding without an actionable fix is incomplete. This is the single biggest thing that separates a useful validation from a generic lint.

Close with the total: "N error(s), M warning(s), K suggestion(s)."

Common Pitfalls

More Info

• template.json reference — full schema
• Available Symbol Generators — generator types
• Post-action registry — action IDs
• Constraints — constraint types