docs: Clarify case sensitivity behavior for JSON keys vs object properties

[vaceslav]

Summary

Clarifies documentation about case sensitivity to accurately reflect implementation behavior:

• JSON dictionary keys ARE case-sensitive
• C# object properties are case-insensitive
• Template authors using JSON should always match exact case for reliability

Background

During a comprehensive documentation-vs-implementation audit, we discovered that the documentation stated placeholder names are "case-sensitive" without nuance. The actual implementation (see PropertyPathResolver.cs:143-144) uses BindingFlags.IgnoreCase for C# object properties, but dictionary keys (JSON data) remain case-sensitive by nature.

This created confusion: the documentation was technically correct for JSON users (the primary audience) but incomplete.

Changes

1. docs/for-template-authors/placeholders.md

Before:

Remember that placeholder names are case-sensitive

After:

Placeholder name matching depends on your data structure:

Dictionary keys (JSON) are case-sensitive: [examples]

Note for developers: If your data comes from code (not JSON files), property names may be case-insensitive depending on how the data is structured.

2. docs/for-template-authors/template-syntax.md

Before:

Placeholder names are case-sensitive. {{Name}} and {{name}} are different.

After:

JSON keys are case-sensitive. {{Name}} and {{name}} are different. Always match the exact case used in your JSON data.

3. docs/for-template-authors/best-practices.md

Before:

Case-sensitive matching:

After:

JSON keys are case-sensitive:

Always match the exact case from your JSON data.

Why This Matters

For Template Authors (primary audience):

• They use JSON files where keys ARE case-sensitive
• Documentation now clearly states this
• Best practice guidance is accurate

For Developers:

• Small note acknowledges that C# objects behave differently
• Doesn't confuse template authors with implementation details
• Maintains focus on JSON use case

Testing

• Documentation changes reviewed for accuracy
• Checked against actual implementation in PropertyPathResolver.cs
• Maintains beginner-friendly tone for template authors
• No C# code examples in template author docs

Related

This fix emerged from a comprehensive documentation audit that also resulted in:

• Issue feat: Implement non-boolean format specifiers (uppercase, lowercase, currency, number, date) #22 - Documents missing non-boolean format specifier implementations

Impact

• Template authors get accurate, clear guidance
• No behavior changes - purely documentation clarification
• Reduces confusion about case sensitivity rules

---

Checklist:

• Documentation accurately reflects implementation
• Template author focus maintained (no unnecessary C# details)
• Best practices updated
• All three relevant files updated consistently

[Copilot]

Pull request overview

This PR clarifies documentation on case sensitivity behavior to distinguish between JSON dictionary keys (case-sensitive) and C# object properties (case-insensitive). The documentation now accurately reflects the implementation while maintaining focus on template authors who primarily work with JSON data.

Key Changes:

• Updates messaging from "placeholder names are case-sensitive" to "JSON keys are case-sensitive" for precision
• Adds a developer note in placeholders.md acknowledging that C# object properties may behave differently
• Ensures consistent, accurate guidance across all template author documentation

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/for-template-authors/template-syntax.md	Updated case sensitivity section to specify JSON keys are case-sensitive with guidance to match exact case in JSON data
docs/for-template-authors/placeholders.md	Expanded case sensitivity explanation with distinction between JSON keys (case-sensitive) and C# properties (case-insensitive), plus best practice guidance
docs/for-template-authors/best-practices.md	Updated best practices header and added explicit guidance to match exact case from JSON data

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Missing period at the end of the sentence. Should be: "Always match the exact case used in your JSON keys to avoid confusion and ensure templates work reliably."

Suggested change

	**Best practice for template authors:** Always match the exact case used in your JSON keys to avoid confusion and ensure templates work reliably
	**Best practice for template authors:** Always match the exact case used in your JSON keys to avoid confusion and ensure templates work reliably.

[vaceslav]

✅ Fixed! Added missing period at the end of the sentence. Thanks for catching this!