Aqua ProtocolAqua Protocol
Aqua Protocol
Aqua ProtocolAqua

Documentation

Welcome to Aqua ProtocolQuick StartDevelopment GuideVersion v4 (beta)
Use Cases
Document VerificationIdentity AttestationAqua Protocol Use CasesSupply Chain Tracking
Development Tools
Aqua CLIAqua SDKAquafier API
Schema Reference
Aqua TreeFile IndexAqua Protocol Schema Reference
Revision Types
Link RevisionObject RevisionAqua Protocol RevisionsSignature RevisionTemplate RevisionWitness Revision

Documentation

Welcome to Aqua ProtocolQuick StartDevelopment GuideVersion v4 (beta)
Use Cases
Document VerificationIdentity AttestationAqua Protocol Use CasesSupply Chain Tracking
Development Tools
Aqua CLIAqua SDKAquafier API
Schema Reference
Aqua TreeFile IndexAqua Protocol Schema Reference
Revision Types
Link RevisionObject RevisionAqua Protocol RevisionsSignature RevisionTemplate RevisionWitness Revision
Docs
Schema Reference
Revision
Template Revision

Template Revision

Schema specification for Template Revisions in Aqua Protocol v4

7 min read

Template Revision

A Template Revision defines the structure and validation rules for Object Revisions. Templates use JSON Schema to specify what data fields are required, their types, formats, and constraints. Template revisions are standalone (they don't have a previous_revision field) and are referenced by object revisions via their hash.

Overview

Template revisions serve as the "type system" for Aqua Protocol. They:

  • Define schemas using JSON Schema (Draft 2020-12)
  • Are immutable once created (identified by their hash)
  • Can be reused by multiple object revisions
  • Optionally reference code implementations
  • Enable validation and type safety

Schema Structure

Fields

FieldTypeRequiredDescription
revision_typestringYesAlways "template" for template revisions
noncestringYesRandom 16-byte hex string for uniqueness
local_timestampnumberYesUnix timestamp when the template was created
versionstringYesProtocol version: "https://aqua-protocol.org/docs/v4/schema"
methodstringYesCanonicalization method: "scalar" or "tree" (typically "scalar")
hash_typestringYesHash algorithm: "FIPS_202-SHA3-256"
schemaobjectYesJSON Schema (Draft 2020-12) that validates object payloads
code_revision_refstringNoOptional hash reference to code that implements this template

Field Details

revision_type

  • Value: Always "template"
  • Purpose: Identifies this as a template revision
  • Note: Unlike object revisions, this is a string constant, not a hash reference

schema

  • Format: Valid JSON Schema (Draft 2020-12 specification)
  • Purpose: Defines validation rules for object revision payloads
  • Required fields in schema:
    • $schema: Should be "https://json-schema.org/draft/2020-12/schema"
    • type: Typically "object"
    • properties: Defines the payload structure
    • required: Lists mandatory fields
    • additionalProperties: Usually false for strict validation

code_revision_ref

  • Format: Hex string reference to another revision (optional)
  • Purpose: Links to executable code or scripts that work with this template
  • Use case: For templates that need associated processing logic
  • Example: Reference to smart contract code, validation scripts, or transformation functions

Examples

Example 1: File Template

A template for storing file metadata:

Code
json
1{
2  "revision_type": "template",
3  "nonce": "0x2ba6a8b9b987cf8c3567f72871812ae9",
4  "local_timestamp": 1762266013,
5  "version": "https://aqua-protocol.org/docs/v4/schema",
6  "method": "scalar",
7  "hash_type": "FIPS_202-SHA3-256",
8  "schema": {
9    "$schema": "https://json-schema.org/draft/2020-12/schema",
10    "type": "object",
11    "properties": {
12      "payload_type": {
13        "type": "string",
14        "maxLength": 128
15      },
16      "hash": {
17        "type": "string",
18        "pattern": "^0x[0-9a-f]{64,128}$"
19      },
20      "hash_type": {
21        "description": "Hash function identifier",
22        "anyOf": [
23          {
24            "type": "string",
25            "const": "FIPS_202-SHA3-256"
26          },
27          {
28            "type": "string",
29            "minLength": 1,
30            "maxLength": 128
31          }
32        ]
33      },
34      "descriptor": {
35        "type": "string",
36        "maxLength": 140
37      }
38    },
39    "required": [
40      "payload_type",
41      "hash",
42      "hash_type",
43      "descriptor"
44    ],
45    "additionalProperties": false
46  }
47}

Hash of this template: 0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e

This hash is what object revisions use in their revision_type field to reference this template.

Example 2: Domain Claim Template

A template for domain ownership claims:

Code
json
1{
2  "revision_type": "template",
3  "nonce": "0x0da37dc1685f4d78a87c9462b0e87685",
4  "local_timestamp": 1762817552,
5  "version": "https://aqua-protocol.org/docs/v4/schema",
6  "method": "scalar",
7  "hash_type": "FIPS_202-SHA3-256",
8  "schema": {
9    "$schema": "https://json-schema.org/draft/2020-12/schema",
10    "type": "object",
11    "properties": {
12      "domain": {
13        "type": "string",
14        "format": "idn-hostname"
15      },
16      "wallet_address": {
17        "type": "string",
18        "pattern": "^0x[0-9a-fA-F]{40}$"
19      }
20    },
21    "required": [
22      "domain",
23      "wallet_address"
24    ],
25    "additionalProperties": false
26  }
27}

Example 3: Email Claim Template

A template for email verification claims:

Code
json
1{
2  "revision_type": "template",
3  "nonce": "0x5c8f9a1b2d3e4f5a6b7c8d9e0f1a2b3c",
4  "local_timestamp": 1762820000,
5  "version": "https://aqua-protocol.org/docs/v4/schema",
6  "method": "scalar",
7  "hash_type": "FIPS_202-SHA3-256",
8  "schema": {
9    "$schema": "https://json-schema.org/draft/2020-12/schema",
10    "type": "object",
11    "properties": {
12      "email": {
13        "type": "string",
14        "format": "email"
15      },
16      "wallet_address": {
17        "type": "string",
18        "pattern": "^0x[0-9a-fA-F]{40}$"
19      },
20      "verified_at": {
21        "type": "integer",
22        "description": "Unix timestamp of verification"
23      }
24    },
25    "required": [
26      "email",
27      "wallet_address"
28    ],
29    "additionalProperties": false
30  }
31}

Example 4: Template with Code Reference

A template that references associated code:

Code
json
1{
2  "revision_type": "template",
3  "nonce": "0x7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a",
4  "local_timestamp": 1762825000,
5  "version": "https://aqua-protocol.org/docs/v4/schema",
6  "method": "scalar",
7  "hash_type": "FIPS_202-SHA3-256",
8  "schema": {
9    "$schema": "https://json-schema.org/draft/2020-12/schema",
10    "type": "object",
11    "properties": {
12      "calculation_type": {
13        "type": "string",
14        "enum": ["sum", "average", "weighted"]
15      },
16      "values": {
17        "type": "array",
18        "items": {
19          "type": "number"
20        }
21      }
22    },
23    "required": ["calculation_type", "values"],
24    "additionalProperties": false
25  },
26  "code_revision_ref": "0x3f8a7b2c9d1e4f5a6b8c0d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a"
27}

Built-in Templates

The Aqua RS SDK provides several built-in templates with pre-computed hashes:

TemplatePurposeHash Reference
FileFile metadata storage0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e
DomainDomain ownership claims(computed at runtime)
EmailEmail verification(computed at runtime)
NameName claims(computed at runtime)
PhonePhone verification(computed at runtime)
AttestationGeneral attestations(computed at runtime)

These templates are defined in the SDK at src/schema/templates/ and can be used directly without creating new template revisions.

JSON Schema Features

Template schemas support all JSON Schema Draft 2020-12 features:

Type Validation

Code
json
1{
2  "type": "string"  // or "number", "integer", "boolean", "array", "object", "null"
3}

Format Validation

Code
json
1{
2  "type": "string",
3  "format": "email"  // or "date", "date-time", "uri", "hostname", etc.
4}

Pattern Matching

Code
json
1{
2  "type": "string",
3  "pattern": "^0x[0-9a-f]{40}$"
4}

Length Constraints

Code
json
1{
2  "type": "string",
3  "minLength": 1,
4  "maxLength": 100
5}

Numeric Constraints

Code
json
1{
2  "type": "number",
3  "minimum": 0,
4  "maximum": 100,
5  "multipleOf": 0.01
6}

Array Constraints

Code
json
1{
2  "type": "array",
3  "items": { "type": "string" },
4  "minItems": 1,
5  "maxItems": 10,
6  "uniqueItems": true
7}

Enumerations

Code
json
1{
2  "type": "string",
3  "enum": ["option1", "option2", "option3"]
4}

Conditional Schemas

Code
json
1{
2  "anyOf": [
3    { "type": "string", "const": "FIPS_202-SHA3-256" },
4    { "type": "string", "minLength": 1 }
5  ]
6}

Validation Rules

A Template Revision is valid if:

  1. Structure: Contains all required fields with correct types
  2. Revision Type: The revision_type field is exactly "template"
  3. Version: Matches "https://aqua-protocol.org/docs/v4/schema"
  4. Schema: Is a valid JSON Schema (Draft 2020-12)
  5. Schema Root: The schema should define an object type at the root level
  6. No Previous Revision: Templates never have a previous_revision field
  7. Code Reference: If present, code_revision_ref must be a valid hash reference
  8. Hash Verification: The computed hash can be verified

Template Lifecycle

1. Creation

Create JSON Schema � Generate Template Revision � Compute Hash

2. Publication

Template Hash � Used by Object Revisions � Enables Validation

3. Reuse

Multiple Objects � Reference Same Template � Consistent Validation

Best Practices

1. Use Descriptive Property Names

Code
json
1{
2  "properties": {
3    "email_address": { "type": "string", "format": "email" },
4    "verified_at_timestamp": { "type": "integer" }
5  }
6}

2. Always Set additionalProperties

Code
json
1{
2  "additionalProperties": false  // Strict validation
3}

3. Include Descriptions

Code
json
1{
2  "properties": {
3    "status": {
4      "type": "string",
5      "description": "Current verification status: pending, verified, or rejected"
6    }
7  }
8}

4. Use Appropriate Constraints

Code
json
1{
2  "email": {
3    "type": "string",
4    "format": "email",
5    "maxLength": 254  // RFC 5321 limit
6  }
7}

5. Plan for Forward Compatibility

  • Avoid overly restrictive patterns
  • Use anyOf for accepting multiple formats
  • Consider optional fields for future extensions

Relationship with Other Revisions

  • Object Revisions: Reference templates via their revision_type field
  • Code Revisions: Can be referenced via code_revision_ref (optional)
  • No Chaining: Templates don't form chains; they're standalone definitions

Implementation Notes

Creating a Template

  1. Design your JSON Schema based on your data requirements
  2. Validate the schema itself is valid JSON Schema
  3. Create the template revision structure
  4. Generate a random nonce
  5. Compute the template hash
  6. Store the hash for use in object revisions

Using a Template

  1. Reference the template hash in the object's revision_type
  2. Ensure payload conforms to the template schema
  3. Validate payload against schema before creating object revision

Template Validation

When validating an object against a template:

1. Retrieve template by hash 2. Extract JSON Schema from template 3. Validate object payload against schema 4. Check validation result

Common Use Cases

Document Templates

Define structure for document metadata, file hashes, and descriptors.

Credential Templates

Specify required fields for verifiable credentials (email, domain, phone, etc.).

Data Exchange Templates

Standardize data formats for interoperability between systems.

Smart Contract Templates

Link templates to on-chain contract code for decentralized validation.

See Also

  • Object Revision - Use templates to validate objects
  • JSON Schema Specification - Full JSON Schema documentation
Edit this pageReport an issue
Previous
Signature Revision
Next
Witness Revision

Documentation

  • Getting Started
  • API Reference

Community

  • GitHub
  • Discord

Copyright © 2024 Aqua. All rights reserved.

On this page

OverviewSchema StructureFieldsField DetailsExamplesExample 1: File TemplateExample 2: Domain Claim TemplateExample 3: Email Claim TemplateExample 4: Template with Code ReferenceBuilt-in TemplatesJSON Schema FeaturesType ValidationFormat ValidationPattern MatchingLength ConstraintsNumeric ConstraintsArray ConstraintsEnumerationsConditional SchemasValidation RulesTemplate Lifecycle1. Creation2. Publication3. ReuseBest Practices1. Use Descriptive Property Names2. Always Set additionalProperties3. Include Descriptions4. Use Appropriate Constraints5. Plan for Forward CompatibilityRelationship with Other RevisionsImplementation NotesCreating a TemplateUsing a TemplateTemplate ValidationCommon Use CasesDocument TemplatesCredential TemplatesData Exchange TemplatesSmart Contract TemplatesSee Also