verstak-sdk/schemas/sync.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://git.mirv.top/verstak/verstak-sdk/schemas/sync.json",
  "title": "Verstak Sync Operations",
  "description": "Sync operation schemas for vault synchronization between devices",
  "type": "object",
  "properties": {
    "SyncOperation": {
      "$ref": "#/$defs/SyncOperation"
    },
    "SyncBatch": {
      "$ref": "#/$defs/SyncBatch"
    },
    "SyncManifest": {
      "$ref": "#/$defs/SyncManifest"
    }
  },
  "$defs": {
    "SyncOperation": {
      "type": "object",
      "description": "A single sync operation entry",
      "required": ["op", "id", "timestamp"],
      "properties": {
        "op": {
          "type": "string",
          "description": "Operation type",
          "enum": ["add", "modify", "delete", "rename"]
        },
        "id": {
          "type": "string",
          "description": "Unique operation identifier (UUID)"
        },
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 timestamp of the operation"
        },
        "deviceId": {
          "type": "string",
          "description": "Originating device identifier"
        },
        "entityType": {
          "type": "string",
          "description": "Entity type being synced",
          "enum": ["file", "note", "plugin_state", "vault_meta"]
        },
        "entityPath": {
          "type": "string",
          "description": "Entity path relative to vault root"
        },
        "hash": {
          "type": "string",
          "description": "Content hash (SHA-256) for content verification"
        },
        "size": {
          "type": "integer",
          "description": "File size in bytes"
        },
        "mimeType": {
          "type": "string",
          "description": "MIME type of the entity"
        },
        "pluginNamespace": {
          "type": "string",
          "description": "Plugin namespace, if syncing plugin state"
        },
        "oldPath": {
          "type": "string",
          "description": "Previous path for rename operations"
        },
        "metadata": {
          "type": "object",
          "description": "Arbitrary metadata key-value pairs",
          "additionalProperties": { "type": "string" }
        }
      }
    },
    "SyncBatch": {
      "type": "object",
      "description": "A batch of sync operations sent between devices",
      "required": ["batchId", "deviceId", "operations", "timestamp"],
      "properties": {
        "batchId": {
          "type": "string",
          "description": "Unique batch identifier (UUID)"
        },
        "deviceId": {
          "type": "string",
          "description": "Originating device identifier"
        },
        "operations": {
          "type": "array",
          "description": "List of sync operations in this batch",
          "items": {
            "$ref": "#/$defs/SyncOperation"
          }
        },
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 timestamp of batch creation"
        },
        "lastSyncTimestamp": {
          "type": "string",
          "description": "Timestamp of the last successful sync from this device"
        },
        "sequence": {
          "type": "integer",
          "description": "Sequence number for ordering batches"
        }
      }
    },
    "SyncManifest": {
      "type": "object",
      "description": "Vault sync manifest for initial reconciliation",
      "required": ["deviceId", "entries"],
      "properties": {
        "deviceId": { "type": "string" },
        "entries": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["path", "hash", "updatedAt"],
            "properties": {
              "path": { "type": "string" },
              "hash": { "type": "string" },
              "size": { "type": "integer" },
              "updatedAt": { "type": "string" },
              "deleted": { "type": "boolean", "default": false }
            }
          }
        }
      }
    },
    "Conflict": {
      "type": "object",
      "description": "Conflict record when two devices modify the same entity",
      "required": ["entityPath", "localHash", "remoteHash", "localTimestamp", "remoteTimestamp"],
      "properties": {
        "entityPath": { "type": "string" },
        "localHash": { "type": "string" },
        "remoteHash": { "type": "string" },
        "localTimestamp": { "type": "string" },
        "remoteTimestamp": { "type": "string" },
        "resolution": {
          "type": "string",
          "enum": ["local_wins", "remote_wins", "manual"],
          "description": "How the conflict was resolved"
        },
        "resolvedAt": { "type": "string" }
      }
    },
    "PairingRequest": {
      "type": "object",
      "description": "Device pairing request payload",
      "required": ["deviceName", "deviceType", "publicKey"],
      "properties": {
        "deviceName": { "type": "string" },
        "deviceType": {
          "type": "string",
          "enum": ["desktop", "mobile"]
        },
        "publicKey": { "type": "string", "description": "Device public key for auth" },
        "clientVersion": { "type": "string" }
      }
    },
    "PairingResponse": {
      "type": "object",
      "description": "Device pairing response",
      "required": ["deviceId", "token", "pairedAt"],
      "properties": {
        "deviceId": { "type": "string" },
        "token": { "type": "string", "description": "Auth token for this device" },
        "pairedAt": { "type": "string" },
        "serverVersion": { "type": "string" }
      }
    }
  }
}