Skip to main content

Templates

⚠️ Future Content: The advanced technical template implementation and custom template development guides below will be provided in future documentation updates. Template marketplace integration and enterprise template management features are being developed for the platform.

Templates define the structure and behavior of digital twins in Filedgr. They act as blueprints that specify what data to collect, how to organize it, and how to verify it for specific use cases.

What are Templates?​

Templates are predefined blueprints that define:

  • Data structure - Required fields, data types, and relationships
  • Validation rules - What constitutes valid data
  • UI components - How data is displayed and input
  • Compliance logic - Regulatory requirements and reporting
  • Integration points - APIs and webhook configurations

Think of templates as smart forms that not only collect data but also verify it, organize it, and make it actionable.

Template Types​

Standard Templates​

Pre-built templates for common asset types and industry use cases:

  • General Document Template - Basic file verification and timestamping
  • Supply Chain Template - Product tracking from origin to consumer
  • Financial Asset Template - Investment tracking and proof of reserves
  • Healthcare Record Template - HIPAA-compliant medical documentation
  • Real Estate Template - Property ownership and transaction history
  • Legal Document Template - Contract verification and compliance
  • Sustainability Template - ESG metrics and environmental compliance

Custom Templates​

Create specialized templates for unique business needs:

// Example custom template structure
const customTemplate = {
  id: "manufacturing-batch-v1",
  name: "Manufacturing Batch Template",
  version: "1.0.0",
  fields: [
    {
      name: "batchNumber",
      type: "string",
      required: true,
      validation: "^BATCH-[0-9]{6}$"
    },
    {
      name: "productionDate",
      type: "date",
      required: true
    },
    {
      name: "qualityMetrics",
      type: "object",
      properties: {
        defectRate: { type: "number", min: 0, max: 100 },
        testResults: { type: "array", items: { type: "string" } }
      }
    }
  ],
  requiredDocuments: ["quality-certificate", "batch-report"],
  complianceRules: ["ISO-9001", "FDA-CFR-21"]
};

Template Structure​

Field Definitions​

Templates specify exactly what data to collect:

{
  "fields": [
    {
      "name": "serialNumber",
      "type": "string",
      "required": true,
      "description": "Unique product identifier",
      "validation": {
        "pattern": "^[A-Z]{3}-[0-9]{8}$",
        "message": "Format: ABC-12345678"
      }
    },
    {
      "name": "weight",
      "type": "number",
      "required": false,
      "unit": "kg",
      "validation": {
        "min": 0,
        "max": 1000
      }
    },
    {
      "name": "category",
      "type": "enum",
      "required": true,
      "options": ["electronics", "clothing", "food", "other"]
    }
  ]
}

Document Requirements​

Specify what files must be attached:

{
  "requiredDocuments": [
    {
      "type": "certificate",
      "name": "Quality Certificate",
      "formats": ["pdf", "jpg", "png"],
      "required": true
    },
    {
      "type": "manual",
      "name": "User Manual",
      "formats": ["pdf"],
      "required": false
    }
  ]
}

Validation Rules​

Ensure data quality and compliance:

{
  "validationRules": [
    {
      "field": "expirationDate",
      "rule": "future_date",
      "message": "Expiration must be in the future"
    },
    {
      "field": "price",
      "rule": "positive_number",
      "message": "Price must be greater than 0"
    },
    {
      "fields": ["startDate", "endDate"],
      "rule": "date_range",
      "message": "End date must be after start date"
    }
  ]
}

Working with Templates​

List Available Templates​

curl -X GET "https://api.filedgr.io/templates" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "templates": [
    {
      "id": "general-template-v1",
      "name": "General Document Template",
      "description": "Basic template for document verification",
      "version": "1.0.0",
      "category": "general",
      "author": "filedgr",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "supply-chain-v2",
      "name": "Supply Chain Template",
      "description": "Advanced supply chain tracking",
      "version": "2.1.0",
      "category": "supply-chain",
      "author": "filedgr",
      "createdAt": "2024-01-15T00:00:00Z"
    }
  ]
}

Get Template Details​

curl -X GET "https://api.filedgr.io/templates/supply-chain-v2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": "supply-chain-v2",
  "name": "Supply Chain Template",
  "version": "2.1.0",
  "description": "Track products through entire supply chain",
  "fields": [
    {
      "name": "productName",
      "type": "string",
      "required": true,
      "description": "Name of the product"
    },
    {
      "name": "origin",
      "type": "object",
      "required": true,
      "properties": {
        "country": { "type": "string", "required": true },
        "facility": { "type": "string", "required": true },
        "coordinates": { 
          "type": "object",
          "properties": {
            "lat": { "type": "number" },
            "lng": { "type": "number" }
          }
        }
      }
    }
  ],
  "requiredDocuments": ["origin-certificate", "quality-report"],
  "complianceStandards": ["ISO-22000", "GS1"],
  "uiConfig": {
    "theme": "supply-chain",
    "layout": "tabbed",
    "widgets": ["map", "timeline", "certificate-viewer"]
  }
}

Creating Custom Templates​

Template Development Process​

  1. Define Requirements

    • Identify data to collect
    • Determine validation rules
    • Specify compliance needs

  2. Design Structure

    • Create field definitions
    • Set up relationships
    • Plan user interface

  3. Test and Validate

    • Create sample vaults
    • Test data validation
    • Verify compliance rules

  4. Deploy and Version

    • Submit for review
    • Deploy to production
    • Manage versions

Custom Template Example​

// Create custom template
const customTemplate = {
  name: "Vehicle Inspection Template",
  description: "Comprehensive vehicle inspection and certification",
  version: "1.0.0",
  category: "automotive",
  fields: [
    {
      name: "vin",
      type: "string",
      required: true,
      validation: {
        pattern: "^[A-HJ-NPR-Z0-9]{17}$",
        message: "Valid VIN required (17 characters)"
      },
      description: "Vehicle Identification Number"
    },
    {
      name: "inspectionDate",
      type: "date",
      required: true,
      validation: {
        rule: "past_or_present",
        message: "Inspection date cannot be in future"
      }
    },
    {
      name: "mileage",
      type: "number",
      required: true,
      unit: "miles",
      validation: {
        min: 0,
        max: 999999
      }
    },
    {
      name: "condition",
      type: "enum",
      required: true,
      options: ["excellent", "good", "fair", "poor"],
      description: "Overall vehicle condition"
    },
    {
      name: "safetyChecks",
      type: "object",
      required: true,
      properties: {
        brakes: { type: "boolean", required: true },
        lights: { type: "boolean", required: true },
        tires: { type: "boolean", required: true },
        emissions: { type: "boolean", required: true }
      }
    }
  ],
  requiredDocuments: [
    {
      type: "inspection-report",
      name: "Official Inspection Report",
      formats: ["pdf"],
      required: true
    },
    {
      type: "photos", 
      name: "Vehicle Photos",
      formats: ["jpg", "png"],
      required: true,
      maxFiles: 10
    }
  ],
  complianceStandards: ["DOT-FMVSS", "EPA-Emissions"],
  workflows: [
    {
      name: "inspection-complete",
      trigger: "all_required_data_present",
      actions: [
        "generate-certificate",
        "notify-owner",
        "update-registry"
      ]
    }
  ]
};

// Submit template for creation
const response = await fetch('https://api.filedgr.io/templates', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(customTemplate)
});

Template Versioning​

Version Management​

Templates use semantic versioning (semver):

  • Major version (1.0.0 → 2.0.0) - Breaking changes that affect existing vaults
  • Minor version (1.0.0 → 1.1.0) - New features, backward compatible
  • Patch version (1.0.0 → 1.0.1) - Bug fixes, no functionality changes

Migration Strategy​

When templates are updated:

// Handle template migration
const migration = {
  fromVersion: "1.0.0",
  toVersion: "1.1.0",
  changes: [
    {
      type: "field_added",
      field: "sustainabilityScore",
      default: null
    },
    {
      type: "validation_updated", 
      field: "price",
      oldRule: "min: 0",
      newRule: "min: 0.01"
    }
  ],
  backwardCompatible: true,
  migrationRequired: false
};

Template Evolution​

Best practices for template updates:

  1. Maintain Compatibility - Avoid breaking existing vaults
  2. Gradual Migration - Phase out old versions slowly
  3. Clear Communication - Document all changes
  4. Testing - Validate migrations thoroughly

IPFS Deployment​

Templates are deployed to IPFS during vault creation, ensuring:

Immutable Versions​

  • Each template version gets a unique IPFS hash
  • Cannot be changed once deployed
  • Permanent availability across the network

Decentralized Access​

  • No single point of failure
  • Global content delivery
  • Censorship resistance

Version Integrity​

// Template deployment info
const deploymentInfo = {
  templateId: "supply-chain-v2",
  version: "2.1.0", 
  ipfsHash: "QmX4k5m8r7j2H9z3...",
  deployedAt: "2024-01-15T10:30:00Z",
  nodes: [
    "ipfs.filedgr.com",
    "gateway.pinata.cloud",
    "cloudflare-ipfs.com"
  ]
};

Template Marketplace​

Public Templates​

Browse and use community-created templates:

curl -X GET "https://api.filedgr.io/templates/marketplace" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Template Sharing​

Share your custom templates:

// Publish template to marketplace
await filedgr.templates.publish({
  templateId: "my-custom-template-v1",
  public: true,
  license: "MIT",
  description: "Template for tracking medical devices",
  tags: ["healthcare", "medical-device", "FDA"]
});

Community Contributions​

  • Rate templates based on usefulness
  • Fork and modify existing templates
  • Contribute improvements back to community
  • Request features for popular templates

Integration Examples​

React Application​

import { useFiledgr } from '@filedgr/react';

function CreateVaultForm() {
  const { templates, createVault } = useFiledgr();
  const [selectedTemplate, setSelectedTemplate] = useState(null);
  
  useEffect(() => {
    templates.list().then(setTemplates);
  }, []);
  
  const handleSubmit = async (formData) => {
    const vault = await createVault({
      templateId: selectedTemplate.id,
      name: formData.name,
      data: formData
    });
    
    console.log('Vault created:', vault.id);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <TemplateSelector 
        templates={templates}
        onSelect={setSelectedTemplate}
      />
      {selectedTemplate && (
        <DynamicForm 
          template={selectedTemplate}
          onSubmit={handleSubmit}
        />
      )}
    </form>
  );
}

Node.js Backend​

const { Filedgr } = require('@filedgr/sdk');

const filedgr = new Filedgr({
  apiKey: process.env.FILEDGR_API_KEY,
  apiSecret: process.env.FILEDGR_API_SECRET
});

// Dynamic vault creation based on template
async function processIncomingData(data, templateId) {
  try {
    // Get template to understand structure
    const template = await filedgr.templates.get(templateId);
    
    // Validate data against template
    const validationResult = template.validate(data);
    if (!validationResult.valid) {
      throw new Error(`Invalid data: ${validationResult.errors.join(', ')}`);
    }
    
    // Create vault with validated data
    const vault = await filedgr.vaults.create({
      templateId: template.id,
      name: `Auto-generated ${template.name}`,
      data: data
    });
    
    return vault;
  } catch (error) {
    console.error('Template processing failed:', error);
    throw error;
  }
}

Best Practices​

Template Design​

  • Keep it simple - Only include necessary fields
  • Clear descriptions - Help users understand what's needed
  • Sensible defaults - Pre-fill common values
  • Flexible validation - Don't be overly restrictive

Performance​

  • Minimize fields - Fewer fields = faster processing
  • Optimize file sizes - Compress large documents
  • Use appropriate types - Choose most specific data type
  • Cache frequently used templates - Reduce API calls

Compliance​

  • Regular reviews - Update templates as regulations change
  • Document requirements - Clear compliance mapping
  • Test thoroughly - Validate against actual regulations
  • Version carefully - Track compliance-related changes

Next Steps​

Templates are the foundation of everything you build in Filedgr. Take time to design them well, and everything else becomes much easier.