> For the complete documentation index, see [llms.txt](https://guardian.hedera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guardian.hedera.com/docs/develop/guardian/workspace/schema-templates.md).

# Schema Templates

### The problem it solves

Policy authors often need to reuse the same schema standard across multiple policies. Without Schema Templates, each policy owns and maintains its schemas independently. This makes it hard to apply a shared standard, control which schema parts may be changed, and safely update policies when the standard changes.

Schema Templates solve this by introducing a standalone Guardian entity that owns schemas and template configuration outside a policy. A policy can apply a template, receive policy-local copies of the template schemas and keep template restrictions.

This supports:

* reusable schema standards across policies;
* more than one template applied to the same policy at once, each mapping to a distinct form type or version (for example VCS Project Description v5a and VCS Monitoring Report v5a applied together);
* schema and field restrictions enforced in both UI and backend;
* safe detach from a template without losing imported schemas;
* template versioning and update previews;
* policy import/export with the exact restrictions that were active at export time.

### How it works

A Schema Template is stored as its own entity with name, description, status, version, previous version, topic id, message id, owner, creator, and configuration.

Template schemas are regular Guardian schemas stored with `category = TEMPLATE`. They belong to the template through `templateId`. Each template schema has a stable `templateSchemaId`, and each template field has a stable `templateFieldId`. These identifiers are the logical reference used when schemas are copied to policies or compared across template versions.

Template configuration is a map keyed by template schema identity:

```json
{
  "schemas": {
    "template-schema-id": {
      "schemaSettingsLocked": true,
      "customFieldsLocked": false,
      "guidelines": "Use this schema for project registration data.",
      "featured": true,
      "fields": {
        "template-field-id": {
          "locked": true,
          "guidelines": "Enter the external registry identifier."
        }
      }
    }
  }
}
```

The configuration controls:

* **Change schema settings**: whether schema name, description, and entity type can be changed.
  * `schemaSettingsLocked: false` allows changes. `true` prevents them.
* **Can add custom fields**: lets policy developers add custom fields to the schema.
  * `customFieldsLocked`: `false` allows custom fields, while `true` prevents them.
* **Featured**: marks a template schema so it stands out in schema lists.
  * `featured: true` shows a filled star next to the schema and sorts it first within its topic on the main Schemas grid, and also in policy configurator schema-picker dropdowns. `false` (the default) does neither.
  * Denormalized onto the schema itself as `templateFeatured` when the template is saved, since template configuration is not queryable on its own - this is what powers the grid sort and the star shown outside the template config editor.
* **Can edit selected field**: whether an individual template field can be edited or removed.
  * `locked: false` allows edits or removal. `true` prevents them.
  * Template-owned fields are locked by default.
* **Guidelines**: notes written by the template author for policy developers.
  * Schema guidelines are stored on the schema configuration.
  * Field guidelines are stored on the field configuration.
  * Guidelines are copied into the policy snapshot and shown in the schema editor after the template is applied.

When a template is applied to a policy, Guardian copies the template schemas into the policy topic as `POLICY` schemas. The copied schemas keep `templateId`, `templateSchemaId`, and field-level `templateFieldId` metadata. Guardian also rewrites sub-schema references so copied policy schemas point to each other instead of the original template schemas.

Guardian then creates a policy-specific `SchemaTemplateSnapshot`. The snapshot is the source of truth for restrictions in the policy editor. This is important because draft templates can keep changing during development, while an already-applied policy should not change silently.

The policy stores a lightweight binding with template identity, snapshot id, state hash, apply timestamp, and a schema map from template schema ids to copied policy schema ids. Heavy snapshot content is stored in GridFS.

When a template is detached, Guardian removes the policy binding, deletes the snapshot, clears template metadata from schemas and fields, and keeps the imported schemas as normal editable policy schemas.

When an applied template is updated, Guardian compares:

* the current template selected by the user;
* the snapshot that was applied to the policy;
* the current policy schemas.

The update preview groups changes by schema and field. Locked template fields and locked schema settings are overwritten by the template. Allowed custom fields are preserved. Custom fields are removed when the new template configuration does not allow them. Removed template schemas with policy custom work require user resolution.

### Key distinctions

* Schema Templates are standalone entities, not only another schema category tab.
* Template schemas use `category = TEMPLATE`; copied policy schemas use `category = POLICY`.
* `templateSchemaId` identifies the logical template schema across copies and versions.
* `templateFieldId` identifies the logical template field across copies and versions.
* Policy editor locks come from the applied snapshot, not directly from the mutable template.
* Draft template changes do not automatically change already-applied policies.
* Published templates are immutable; changes require a new draft version.
* Detach removes template restrictions and, unless you ask for the schemas to be deleted as well, keeps the imported schemas.
* Template-owned policy schemas cannot be deleted before detach.
* A policy can have more than one applied template at the same time, each bound independently with its own snapshot and schema map.
* **Schema Templates** on the policy row opens one management dialog listing **Applied templates** (each with its own update and detach action) and **Available templates** (each with an apply action). The action is enabled only on draft policies.
* Updating a binding can either refresh it from the same template or switch it to a different template or version.
* Detaching can optionally delete the copied schemas, except any that another schema in the policy still references.
* A policy linked to a draft template or unresolved snapshot cannot be published.
* Policy import can link to a matching template, select a local template, or detach restrictions.

### Troubleshooting

**Why can't I delete a schema template?**

The template is used by one or more policies. Detach it from every listed policy. Then delete the template.

**Why can't a policy import link to its template?**

The referenced template is unavailable on this instance. In the import preview, select a matching local template. You can also detach template restrictions to continue.

### Related

* Task: [Create a Schema Template](/docs/develop/guardian/workspace/schema-templates/create-a-schema-template.md)
* Task: [Configure Schema Template Guidelines](/docs/develop/guardian/workspace/schema-templates/configure-schema-template-guidelines.md)
* Task: [Mark a Schema as Featured](/docs/develop/guardian/workspace/schema-templates/mark-a-schema-as-featured.md)
* Task: [Apply a Schema Template](/docs/develop/guardian/workspace/schema-templates/apply-a-schema-template.md)
* Task: [Preview a Schema Template](/docs/develop/guardian/workspace/schema-templates/preview-a-schema-template.md)
* Task: [Update an Applied Schema Template](/docs/develop/guardian/workspace/schema-templates/update-an-applied-schema-template.md)
* Task: [Detach a Schema Template](/docs/develop/guardian/workspace/schema-templates/detach-a-schema-template.md)
* Task: [Import a Schema Template](/docs/develop/guardian/workspace/schema-templates/import-a-schema-template.md)
* Task: [Export a Schema Template](/docs/develop/guardian/workspace/schema-templates/export-a-schema-template.md)
* Guardian schemas documentation: [Schemas](https://guardian.hedera.com/guardian/standard-registry/schemas)
* Guardian policies documentation: [Policies](https://guardian.hedera.com/guardian/standard-registry/policies)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guardian.hedera.com/docs/develop/guardian/workspace/schema-templates.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.