template-validation

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.

Parse gate — stop on syntax errors. Parse JSON before applying any semantic rule. If parsing fails, report the parser's line and column, show only the smallest concrete syntax correction, and stop. Do not invent required-field, symbol, post-action, or discoverability findings from a document that did not parse. Re-parse after the correction before making any semantic claim.

The malformed-JSON final response has exactly two parts: the one-line parse verdict and a corrected snippet showing the exact edit. Do not append semantic recommendations, optional metadata, or a full replacement manifest.

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

Custom parameter help is template-specific: it appears under dotnet new <shortName> --help, not the global dotnet new --help. Correct that premise when necessary, then explain which invalid symbol definitions prevent the parameters from appearing reliably.

A valid choice parameter uses a non-empty choices object, for example:

"Color": {
  "type": "parameter",
  "datatype": "choice",
  "defaultValue": "Blue",
  "choices": {
    "Blue": { "displayName": "Blue" },
    "Green": { "displayName": "Green" }
  }
}

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
• For type: "host", missing args is an ERROR. args is a required array; each entry needs hostname. Supported built-in identifiers include dotnetcli, vs, vs-mac, ide, and dotnetcli-preview. An optional version uses NuGet version/range syntax such as [10.0.100,). The engine matches argument keys case-insensitively, so the documented hostName spelling is also valid. Reject unrelated fields such as pattern and value.
• For type: "sdk-version", args is a version string or array using the same syntax.

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 and column. If an absolute-path read fails, retry the user-supplied relative path from the working directory before concluding the file is unavailable.

Only after parsing succeeds, run all 8 validation categories above. Collect errors, warnings, and suggestions separately. Verify schema-sensitive claims against the installed SDK or the current template-engine schema; do not infer a runtime failure from a field name alone.

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)."

For malformed JSON the output is intentionally smaller and has exactly two parts:

❌ Not ready — JSON parse error at line N, column M: <message>.

<smallest corrected fragment showing the exact edit>

Do not append a findings table or semantic totals until the corrected file parses.

Common Pitfalls

More Info

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