# Version Control and Migration

Best practices for version control and migration in Hedera Guardian schemas center on maintaining backward compatibility, clear semantic versioning, planned deprecation, and thorough documentation to ensure smooth transitions across schema updates.

### Version Control Best Practices

* **Semantic Versioning**\
  Use a major.minor.micro format for schema versioning:
  * **Micro**: Non-breaking minor edits (descriptive changes, comments)\
    This convention helps users recognize change impact at a glance and plan accordingly.
  * **Minor**: Non-breaking but notable changes (adding new fields, new enum values, adjusting required/optional status)
  * **Major**: Breaking changes (removing, renaming, or altering field types)
* **Preserve Backward Compatibility**\
  Avoid removing or modifying existing schema elements. Instead, add new fields or enums for new functionality so older schemas remain valid and usable by the Guardian Policy Engine indefinitely.
* **Deprecation Notice and Grace Period**\
  When a schema version or element is deprecated, provide a minimum 2-month notice through metadata annotations and official release notes. Communicate end-of-life dates and issue revocation notices on Hedera Topics at expiry for transparency.
* **Maintain Schema Registry and Metadata**\
  Document all versions, status (active, deprecated, unsupported), and compatibility information in a centralized registry. This facilitates tracking and migration planning.

### Migration Best Practices

* **Versioned Migrations with Clear Documentation**\
  Maintain detailed change logs describing all schema modifications, reasons for change, and migration guides to assist consumers in adapting to newer schema versions.
* **Testing Migration Paths**\
  Thoroughly test backward and forward compatibility of schemas during upgrades using controlled test data and simulations within Guardian.
* **Plan for Obsolete Elements**\
  Prepare tools and processes to phase out obsolete schema elements by removing them from newly created schemas and guiding users on alternate fields.
* **Align Schema Versioning with Policy Engine Releases**\
  Sync schema language changes with Guardian engine updates to manage technological dependencies and leverage new platform capabilities effectively


---

# Agent Instructions: 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:

```
GET https://guardian.hedera.com/guardian-dev/guardian/standard-registry/schemas/best-practices-to-implement-schema/version-control-and-migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.