Schemas and HTML Templates in SitecoreAI: Separating Agent Data from Presentation

The schema should describe what an agent produced. The HTML template should describe how people read it. Keeping those responsibilities separate lets a team validate the result before rendering, reuse it in another layout, and change presentation without asking the model to regenerate the underlying content. It also makes failures easier to locate: a missing source reference is a data problem, while a hidden source reference may be a presentation problem.

This article walks through a proposed campaign-summary design in SitecoreAI. The schema and Handlebars examples are illustrative building blocks, not a complete exported agent definition. Product procedures are grounded in official documentation; integration policies and release records are recommendations. No customer deployment, measured improvement, or tenant-specific validation is claimed. Verify available controls and supported schema behavior in your own environment before adopting the example.

My position is that an agent should usually return meaningful fields rather than final HTML when those fields will be reviewed or reused. Generating finished markup can be reasonable for a disposable prototype. For maintained content workflows, I prefer a stable record because it gives editors and developers something they can inspect independently of the layout. The design below shows how to build that record, render it, and test the boundary between the two.

1. Choose a data contract before choosing a layout

Define the review object

Start with the user’s decision. In the hypothetical campaign-summary task, a reviewer needs to understand the proposed message, intended audience, supporting sources, and unresolved questions. Those concepts belong in the output record. A heading size, card border, or column arrangement belongs in presentation. Do not ask the model to combine them into one large body field simply because that field is easy to display. A record with meaningful properties gives later consumers a clearer contract than a paragraph containing hidden assumptions about layout.

Identify the source inputs separately from the generated output. The campaign brief may supply a market and objective. A product specification may supply factual evidence. The agent may propose wording and recommendations. Preserve those origins where the review needs them. A generated audience description should not be confused with a verified destination identifier or an authenticated reviewer decision. The output schema can represent proposals and uncertainty, while trusted application components establish identity and authority through their supported mechanisms.

Sitecore’s configuration overview distinguishes schemas from HTML templates and describes templates using Handlebars to bind structured fields. Use that distinction as a starting point, not proof that every downstream integration shares one schema. Your CMS content template, agent output schema, and presentation template are different contracts. The first models stored content, the second models generated data, and the third models a view. Define the mapping between them instead of treating their similar names as equivalence.

Choose useful field boundaries

For the example, propose title, summary, recommendations, source references, and unresolved questions. Keep recommendations as a list when users need to review them separately. Give a recommendation a stable local reference if later interactions or corrections must identify it. Avoid storing a list as an HTML fragment merely to preserve bullet styling. The list’s identity and meaning should survive if the team later presents it as cards, a table, or plain text.

Do not make every visible element a generated field. Section labels such as Recommendations can be static template text. A generation timestamp or authenticated creator reference should come from the trusted process if the application needs it. A model should not invent those facts. Distinguish supplied, generated, and observed properties in the contract documentation. This keeps the schema focused on the output’s meaning and prevents an attractive view from encouraging fabricated operational metadata.

Define how missing information appears. An unresolved source question should remain unresolved rather than be replaced with plausible detail. An optional summary may be absent under a deliberate policy, while a required title must meet the task’s requirements. Empty, unknown, and not applicable can mean different things. Choose representations the generator and consumer can both interpret. Do not make the renderer guess which meaning an empty string was intended to convey when that difference affects review.

Keep reuse honest

Imagine the same summary is read in a review document and a compact campaign card. Both views should receive the same identified data revision. The compact view may intentionally omit detail, but it should not imply that omitted uncertainty has been resolved. A label or link can direct the reader to the complete review packet. Define the minimum information each use requires. Reuse is useful only when a view remains appropriate to the decision people make from it.

Separate channel adaptation from styling. Turning a summary into social copy may require a new content transformation, not merely another HTML template. A template should not silently rewrite claims, invent a shorter offer, or infer a different audience to fit a layout. If the task needs adapted wording, generate a distinct output under a defined contract and review it accordingly. Presentation changes can rearrange data; semantic changes need their own evidence and ownership.

Write a short contract note for each property: meaning, source, requiredness, and permitted consumers. A developer should understand whether summary is plain text or approved rich content. An editor should understand whether recommendations are proposed or accepted. An operator should know which record revision a preview uses. The note need not be elaborate. Its value is shared interpretation at the places where data becomes a visible statement or a consequential action.

The acceptance exercise is to describe two layouts without changing the proposed record. If every layout change requires a new generated property or rewritten body, the data contract may be too closely tied to one presentation. Conversely, if a view cannot show the information needed for its decision, the record may be too coarse. Adjust the boundary before adding more generation instructions. That produces a reusable object whose usefulness can be tested separately from visual polish.

2. Define and validate an agent output schema

Create the structure with explicit requirements

Sitecore’s schema authoring guide describes administrator-managed reusable schemas, required fields, types, descriptions, and validation rules. In the documented route, open Agentic, Settings, Schemas, add a schema, define the structure, and save. Use the controls available in your environment. The example here is deliberately small. It should be evaluated with the actual supported schema vocabulary rather than assumed to represent every feature of an external JSON Schema validator.

For a first contract, choose plain text for title and summary and an array of strings for unresolved questions. A later contract can make recommendations structured objects when the workflow needs identity or evidence per recommendation. Resist adding complexity without a consumer requirement. At the same time, do not flatten information that a reviewer must inspect independently. The goal is a small model that preserves the distinctions the task needs, not the shortest possible JSON response.

The following fragment illustrates structural intent. It is not an exported Sitecore agent configuration, and the limits of the generation surface still need checking.

{
  "type": "object",
  "properties": {
    "title": {"type": "string", "description": "Proposed campaign summary title"},
    "summary": {"type": "string", "description": "Plain text grounded in the supplied evidence"},
    "recommendations": {"type": "array", "items": {"type": "string"}},
    "unresolvedQuestions": {"type": "array", "items": {"type": "string"}}
  },
  "required": ["title", "summary", "recommendations", "unresolvedQuestions"],
  "additionalProperties": false
}

Separate descriptions from enforceable rules

A field description can guide generation, but it should not be the only enforcement of a consequential requirement. Writing maximum length in prose is different from configuring a supported constraint and validating the result. Likewise, a description saying source-supported does not prove factual support. Assign structural checks to the schema or trusted validator and evidence checks to the review process. Document which component owns each requirement so failures have a clear diagnosis and correction path.

The JSON Schema object reference explains that declared properties are not automatically required and that null differs from absence. Use those distinctions deliberately. If the contract requires an unresolved-questions list, an empty list can mean the assessment found none under its defined scope. It should not mean the assessment never ran. Add an explicit result state when the workflow must distinguish those cases. Do not let one convenient default conceal missing work.

Decide whether unknown properties are allowed. A closed contract can reveal an unexpected producer change, but it also requires deliberate evolution when new fields are added. An open contract can accommodate extensions, but consumers still need a policy for fields that affect governance. Do not discard a newly introduced warning merely because the old renderer does not recognize it. The correct behavior may be rejection, an explicit unsupported state, or a controlled adapter. Choose that policy before a shared schema changes.

Validate business meaning after shape

A structurally valid summary can name the wrong market or overstate a source. Add checks for the actual task: intended language, selected evidence, allowed destination references if present, and unresolved claims. Some checks can be deterministic. Others require qualified editorial judgment. Keep their results separate from schema validity. A single green label called valid invites users to infer more than the structural check establishes. Name the evidence, such as structure accepted or source review pending.

Build fixtures before connecting the live generation step. Include an ordinary record, a missing title, an unexpected property, an empty recommendations list, and an unresolved question. Add an invalid type to test rejection. For each fixture, state whether the consumer should render it, reject it, or display a limited state. This tests the contract’s behavior. A happy-path example alone cannot establish that the boundary handles the data variation the generator may produce.

Do not repair invalid data by silently inventing facts. A repair stage may correct an exact structural issue under a documented rule, or request a new generation. If it changes meaning, identify the result as a new proposal and preserve its evidence needs. An absent source reference should not be filled with a loosely relevant URL just to make validation pass. My preference is a visible incomplete record over apparently complete data that cannot support the review it is being offered for.

The admitted limitation is that schema validation cannot establish factual correctness or publication authority. It can establish defined structural properties under the validator used. Keep that narrow claim useful by testing it and recording failures clearly. The output of this stage is a schema, representative fixtures, and an ownership note for semantic checks. That is enough to begin rendering without asking the HTML template to become a hidden data-repair or authorization engine.

3. Render the same data through an HTML template

Bind fields without rewriting their meaning

Sitecore’s HTML template guide describes creating a reusable template through Settings, HTML Templates, and mapping fields with Handlebars. Its examples use placeholders, conditionals, and loops. For the campaign summary, the template should display the supplied title and summary, repeat the recommendations, and retain a visible path to unresolved questions. It should not manufacture missing content or convert a proposed recommendation into an approved action through its wording.

Use a simple layout first. An article wrapper, heading, paragraph, and list are enough to test the binding. Keep visual styling separate from the question of whether the right field reaches the right location. When a value is absent, inspect the contract and expected state rather than immediately adding a fallback. A friendly fallback can be appropriate for optional display data, but it can also hide a required field failure. Decide that behavior with the data contract owner.

The example below is Handlebars source shown as code. It is not meant to run inside this blog post.

<article class="campaign-summary">
  <h2>{{title}}</h2>
  <p>{{summary}}</p>
  <h3>Recommendations</h3>
  <ul>
    {{#each recommendations}}<li>{{this}}</li>{{/each}}
  </ul>
  {{#if unresolvedQuestions}}
    <h3>Questions for review</h3>
    <ul>
      {{#each unresolvedQuestions}}<li>{{this}}</li>{{/each}}
    </ul>
  {{/if}}
</article>

Decide what the compact view may omit

Build a second template for a concise review card using the same record. It can emphasize the title and summary and provide a route to the complete recommendations. If unresolved questions exist, keep a visible indication rather than hiding them simply to preserve a clean design. The compact view should communicate its scope. A user deciding whether to proceed should know whether the card is a summary of a complete assessment or a partial view with review work remaining.

Do not insert display-oriented punctuation into the data just to satisfy one layout. A title field should not need a closing HTML tag or a prefix that another template must strip. A recommendation string should not include list-item markup if the contract says plain text. Keep content values meaningful on their own. This makes later exports and alternative layouts easier to inspect and avoids giving every consumer responsibility for undoing presentation choices made during generation.

For rich content, define a separate contract and supported rendering route. Plain text and rich text have different handling needs. Do not switch to raw output merely because a generated string contains markup that looks useful. The Handlebars security guidance explains normal escaping and the risks of bypassing it for untrusted data. Use the actual integration’s approved sanitization and rendering controls when rich content is necessary. The template should not make a generated HTML fragment trusted by declaration.

Keep presentation transformations narrow

Formatting a supplied date or arranging a list may belong in presentation when the integration supports it and the rules are defined. Inferring a missing date or converting an unresolved claim into a confident summary does not. Draw that boundary in the template review. If a helper or application layer performs a transformation, document it and test it separately. Do not assume arbitrary custom helper registration is available through every Sitecore template surface. Use only supported capabilities in the deployment.

Keep static labels honest. Recommendations, proposed copy, and questions for review describe different kinds of content. Avoid a heading such as Approved campaign if the data contains only generated proposals. A template can change the user’s interpretation without changing a single content value. Review the language of headings, status badges, and empty states as part of correctness. Visual hierarchy should help the reader assess evidence rather than imply a stronger decision than the workflow recorded.

Test both templates against the same identified fixture. Compare the title, summary, and unresolved condition in the rendered views. Confirm that the compact view’s omissions follow its intended purpose and do not contradict the detailed view. Keep the fixture unchanged while revising styling. If the data changes too, record that as a separate test because otherwise a successful preview may be attributed to a layout fix when the underlying record was actually altered.

Finish with an editor walkthrough. Ask the editor to locate the main recommendation and an unresolved question in each view. If one template makes the unresolved issue effectively invisible, revise its hierarchy or scope. These are proposed exercises, not observed user-study results. The aim is to demonstrate that presentation changes how information is organized while preserving the meaning and uncertainty that the data contract carries.

Walk one record through two presentations

Consider a hypothetical release note record containing a title, a factual summary, two recommendations, and one unresolved question about regional availability. The record is useful precisely because that final question remains visible. A compact card can shorten the visual treatment, but it should still communicate that a regional point needs review. A longer report can give the question its own paragraph. Both presentations should preserve the same meaning even when their typography and spacing differ.

Start the comparison with a saved fixture rather than another generated response. Capture its revision in the test notes and render it through both templates. Read the result as a reviewer who has never seen the raw record. Can that reader distinguish established information from advice? Can they identify the unresolved issue before acting on the recommendations? A template that passes a superficial screenshot check can still fail this reading task if its visual hierarchy makes tentative advice appear more authoritative than the underlying data supports.

Now alter only the template. Move the recommendations above the summary, remove a decorative container, or change the spacing. The content fixture should stay identical. Record whether the change affects the apparent relationship between claims and caveats. This exercise gives the design reviewer a bounded question: did the new presentation preserve the approved meaning? It avoids mixing a layout revision with a freshly generated answer whose wording, claims, and evidence have also changed.

Next alter the record deliberately. Replace the regional question with a supported answer and attach the relevant evidence through your chosen review process. This is a content change even if both templates produce the same dimensions. Its review should follow the rules for that content, with the previous question and the new answer available for comparison. A familiar layout should not make a new claim inherit an earlier approval.

Finally, inspect a plain text export of the fixture. The title, summary, recommendations, and outstanding question should remain intelligible without their cards, colors, or placement. This is a practical portability check for content destined for more than one channel. If an essential distinction exists only as a color or a position, put that distinction into an explicit field or visible wording and test the templates again. The goal is not to force identical experiences across channels; it is to preserve the information required to interpret the record responsibly.

4. Connect schemas and templates to agent configuration

Connect the resources through the actual agent controls

Sitecore’s configuration overview describes linking schemas and HTML templates through parameter choices and relevant workflow actions. Use that supported model rather than assuming that creating two resources automatically makes every agent use them. For the campaign example, identify which output format or channel option selects the summary contract and which template presents it. Record those references in the configuration you control. A resource existing in Settings is different from a tested agent path actually selecting it.

Choose one bounded generation route for the first implementation. A custom workflow can prepare inputs, obtain the required structured output, and save the result using supported actions. The exact action properties should come from the current editor and documentation. This article does not provide a fabricated universal JSON import. Inspect the selected action’s inputs and outputs in your environment and confirm that the output variable used for rendering is the record you intend to display.

Keep generation instructions aligned with the schema. Explain what title, summary, and recommendations mean for the task, and how to preserve unanswered questions. Do not duplicate the entire HTML layout in the prompt. That asks the model to solve a presentation problem already owned by the template. Likewise, do not rely on a beautifully written prompt to enforce a required property the consumer actually depends on. Use clear instructions and structural validation for their respective responsibilities.

Pass the right value between steps

Inspect the actual result shape when one action feeds another. The structured record may be nested inside an execution envelope. A template expecting title at its root cannot display the intended value if the workflow passes an unrelated wrapper. Define an adapter or field selection using the supported expression mechanism. Do not copy a path from a different tool response and assume it applies here. The acceptance condition is the exact record reaching the intended consumer, with its error state handled separately.

Separate the model’s content from operational metadata. The run identifier and schema selection can be recorded by the integration around the generated record. A reviewer decision should come from the supported review mechanism. Avoid letting a single generated object author both the campaign proposal and the trusted facts that make it eligible for release. A structured output can contain an unresolved condition without being an authorization document. The workflow should preserve that distinction when it saves or renders the artifact.

Decide how an invalid output affects later steps. The workflow can stop for correction, request another generation under a bounded policy, or route a partial draft to a person. It should not render a broken record as if it were a complete campaign summary. Keep the failure explanation useful: identify the missing or invalid field and the stage responsible. Avoid a generic retry that repeats unrelated completed actions or hides an error by substituting empty values throughout the template.

Save and identify the reviewed result

Preserve the source record revision used by the preview where the supported process allows it. If the editor changes the content, identify the new result and determine whether earlier review still applies. A template refresh should not silently attach approval to a different data revision. The surrounding application may need a review packet when a downstream content write is consequential. This is an integration recommendation, not a claim about a native immutable snapshot for every configuration resource.

Keep the original structured data accessible to authorized reviewers or operators. A rendered document alone may omit fields that explain uncertainty or support later conversion. Define what is retained, who can inspect it, and how it links to the displayed artifact. Do not expose restricted source references publicly simply because they exist in the record. Presentation and storage views can differ, provided their relationship is explicit and the reviewer can reach the evidence appropriate to their role.

Test the full route using a fixed input packet. Confirm the selected schema, generated structure, record passed to the template, saved artifact, and visible output. Then repeat with an unresolved question and a deliberately invalid record through a controlled fixture. The expected behavior should be clear from the contract. This checks the wiring around the examples, which is different from proving that the sample schema or template is syntactically reasonable in isolation.

The practical handoff is a small configuration note: which agent path uses the pair, which variable carries the data, what validation runs, and who handles a failure. Ask an operator to locate those facts from the note and run evidence. If only the original builder can explain them, improve the record before expanding reuse. A data-presentation separation is useful only when the workflow actually respects it at execution and maintenance boundaries.

5. Test security, accessibility, and data variation

Test untrusted content at the rendering boundary

Generated text and retrieved source content should be treated according to the renderer’s security model. For ordinary text, use the supported escaped insertion path. Handlebars documents that normal expressions escape HTML, while triple-stash expressions bypass that behavior. Escaping is context specific, so a text-safe value is not automatically safe inside a URL, style, or script context. Keep the example template focused on text. Validate link destinations and use approved rich-content handling when the actual task needs them.

Do not evaluate arbitrary generated code to make the template more flexible. A recommendation can be displayed as data without becoming an executable instruction. If the application needs custom transformations, implement them through supported trusted code and review that code as part of the integration. This article does not assume unrestricted scripting through Sitecore HTML templates. The objective is to keep the model’s output inside an understood contract rather than expand its authority to repair or redesign the runtime.

Create a harmless test fixture containing characters that could be interpreted as markup and inspect how the actual renderer displays them. Add an untrusted URL under the application’s link policy if links are supported. The test should demonstrate the intended encoding and validation behavior in the deployed surface. Do not claim that a local Handlebars demonstration proves the entire product integration secure. Record the layer tested and the controls that belong to the surrounding application.

Exercise content variation before polishing

Use empty lists, long titles, extended summaries, and the languages the workflow expects. A template that looks good with short sample content can hide or truncate the actual review requirement. Decide which limits belong in the schema and which belong in layout. Do not silently cut a material warning to keep cards the same height. A compact view can offer expansion or a detailed view through the supported interface, but the user should know that additional information exists.

Test missing optional values and unsupported result states. An absent image or secondary description may permit a simpler layout. Missing evidence or a failed assessment may require an explicit warning or blocked review outcome. The same fallback should not handle both. Keep the difference visible in fixtures and expected results. A template that turns every absence into a reassuring blank space has not preserved the data contract’s meaning, even if it never throws an exception.

Review accessibility through the actual rendered output. Use meaningful heading structure and readable lists. If a template contains controls, test their names, keyboard access, and focus behavior under the supported surface. The W3C keyboard guidance explains that custom interaction needs implemented behavior. A static review document may need fewer controls than an interactive widget. Do not infer that adding ARIA attributes alone supplies the full user experience or establishes conformance.

Separate layout approval from content approval

An editor can accept the presentation while rejecting a claim. A developer can validate binding while knowing nothing about regional product applicability. Preserve those decisions separately when the workflow needs them. Avoid one broad approved status that seems to cover every dimension. A useful test report states which structural, presentation, and content checks ran and who owns unresolved questions. This prevents a successful visual review from being misused as evidence of factual or release approval.

Use representative fixtures to compare template changes. Keep the data constant when evaluating a visual revision. If a new schema is introduced at the same time, test the supported combinations explicitly. An old record may lack a field the new template expects. The correct behavior might be a limited view or adaptation, not an empty output presented as complete. Treat compatibility as a consumer decision rather than assuming that every additive schema change is harmless to presentation.

Document failures in the language of the affected requirement. Missing title, unsupported record revision, inaccessible evidence, and unreadable long text are different issues. Route them to schema, workflow, content, or presentation owners as appropriate. Do not send every problem back to prompt tuning. A changed field path may need a wiring fix, while a source contradiction needs editorial resolution. Clear ownership makes the separation useful after the first successful demo.

The release evidence should include representative rendered states and the original fixtures under the organization’s access policy. State the limits of the checks. A screenshot demonstrates appearance at one state; it does not establish every possible value or interaction. A schema pass establishes a structural result under a particular validator. The admitted limitation remains deliberate: no combination of those checks automatically proves the content true or grants permission to publish it.

6. Version the pair and release it without confusing presentation with approval

Manage the pair as a maintained contract

Assign owners for the schema, template, and workflow wiring. The same person can own several parts, but the responsibilities should stay explicit. A schema owner evaluates field meaning and structural compatibility. A template owner evaluates faithful presentation. The workflow owner checks selection, variable passing, and saved-result behavior. Editorial owners decide source support and review outcomes. Without that agreement, a shared resource can change under consumers whose maintainers never knew they depended on it.

Preserve a release record for the resources the application controls. Include schema reference, template reference, workflow configuration, and fixture revision where available. Do not invent internal version identifiers the platform does not expose. If shared resources are mutable, determine how the process can preserve relevant configuration evidence or restrict changes while work waits. A release label is useful only when an operator can identify what was actually tested and how a saved artifact relates to it.

Classify schema changes by effect. Adding optional display text differs from changing the meaning of a source-support field. Renaming a property can break a binding even when the content itself is unchanged. A new warning category may require a template update to remain visible. Review the affected consumers before editing shared resources. Do not call a change cosmetic merely because it is a short JSON diff; the consequence depends on the interpretation at the next boundary.

Keep old records readable without inventing facts

Decide how saved artifacts under an older contract will be displayed. A supported adapter may rename a property or supply a clearly defined structural wrapper. It should not fabricate evidence or approvals that the old record never captured. Preserve an unavailable state when needed. The record should remain explainable as data produced under a particular contract, not be rewritten to look as though it had always satisfied the newest expectations.

Handle waiting review packets separately from historical artifacts. A new template may change what a reviewer sees while the underlying proposal is unchanged. A new schema or mapping may change the proposed effect itself. Determine whether a fresh review is required under policy. Do not silently carry an approval from one packet to another because the displayed heading still looks familiar. Keep presentation review and action authorization tied to their actual subjects.

Plan rollback in both directions. Restoring an older template may not make newly produced records compatible with it. Restoring an older schema selection may leave new artifacts waiting in the workflow. Identify affected records through supported references and choose a controlled correction or reader path. Do not assume that configuration rollback erases data already created or actions already issued. A useful runbook states what remains in flight and which owner can resolve incompatible results.

Release through a small evidence-based exercise

For the first release, use one summary task and two layouts. Validate the ordinary record and the meaningful negative fixtures. Run the selected agent route, inspect the saved structured output, and compare both views. Ask an editor to identify an unresolved question and an operator to trace the schema-template pairing. Record actual outcomes when the team performs the exercise. This article proposes that procedure; it does not claim that the example was executed in a Sitecore tenant.

Track correction reasons after release. Suggested categories include invalid structure, wrong binding, hidden uncertainty, unsupported record revision, and substantive editorial correction. These are proposed measurements, not observed improvements. Review examples alongside counts. A lower validation-failure rate is not automatically better if the new contract simply stopped checking a requirement. The purpose of measurement is to improve the specific boundary causing work, not produce a general score that hides where the problem occurred.

Keep the public promise narrow. The schema makes the agent output more predictable under defined checks. The template makes that output readable under defined layouts. Neither replaces source review, destination mapping, or release control. A team can still choose to generate HTML directly for a bounded task, but it should understand the resulting coupling and test it accordingly. The preference for separation is an engineering judgment grounded in inspectability and reuse, not a claim that one architecture fits every possible agent.

The next practical step is to take one existing agent response and separate meaningful data from visual markup. Write the record’s field meanings, build a small schema, and render the same fixed fixture through two templates. Inspect what breaks when fields are absent or unresolved. Fix that boundary before expanding to more channels. The result should be a contract people can validate and a view people can review, with the relationship between them clear enough to maintain.