Documentation and Metadata

Best practices for documentation and metadata in Hedera Guardian schemas emphasize clarity, completeness, standardization, and version control to ensure maintainability, interoperability, and trust across the sustainability ecosystem.

Key Best Practices

• Clear Schema Purpose and Scope Document the schema name, version, and a concise description of its purpose and intended use. This helps all participants understand the context and application of the schema at a glance.

• Field-Level Documentation Provide descriptive labels and user-facing questions for every field. Include guidance notes or help text where needed to clarify expected input and reduce data entry errors.

• Standardized Data Model Annotation Define data types, required status, allowed values (e.g., enums), validation rules, and relationships explicitly in metadata. This supports machine readability and enforces data integrity before on-chain issuance.

• Version History and Change Log Maintain detailed versioning metadata including semantic version number, release date, author, and change summary. Track additions, removals, and modifications between versions for auditability and migration planning.

• Schema Metadata Fields Include metadata fields for:

  • Author/Owner: Responsible party for the schema

  • Date Created/Updated: Timestamps for lifecycle tracking

  • Deprecation Status: Flags and notes if the schema or parts are deprecated

  • External References: Links to related policies, methodologies, or standards.

• Use Structured Formats Maintain documentation alongside JSON schema definitions or Excel templates in human-readable formats supplemented by machine-readable annotations embedded in the schema where supported.

• Interlink Schemas and Modules Reference related schemas or modules explicitly within metadata to indicate composability and relationships, improving navigation and reuse.

• Stakeholder Accessibility Store documentation and metadata in accessible, version-controlled repositories, ensuring all stakeholders (developers, auditors, validators, regulators) have up-to-date schema information.

• Audit Trail and Transparency Leverage Guardian’s trust chain to log schema publications, updates, and deprecation, providing a verifiable provenance record for regulatory and community trust.

• Training and Examples Supplement schema documentation with usage examples, test data, and training materials to facilitate adoption and proper implementation.