Manifest

The manifest.json file is the identity record for an OmniData container. It is a single JSON object that describes who owns the instance, what scope it serves, and which schema version it conforms to.

Schema

{
  "schema_version": 2,
  "instance_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "instance_name": "director-of-ai",
  "owner_identity": "[email protected]",
  "hat_identifier": "director-of-ai",
  "description": "Knowledge container for the Director of AI role",
  "created_at": "2025-11-15T08:30:00Z",
  "updated_at": "2026-03-28T14:22:00Z",
  "metadata": {
    "runtime_version": "0.5.0"
  }
}

Fields

schema_version

Integer. Required. The specification version this container conforms to. Currently 2 for the directory bundle format. Used by runtimes to determine compatibility and apply migrations when future schema versions are released.

instance_id

String (UUID v4). Required. The globally unique identifier for this OmniData instance. Generated once at creation time and never changed, even if the directory is renamed, moved, or copied. This is the stable identity used for federation and cross-instance references.

instance_name

String. Required. A human-readable name for the instance (e.g., "director-of-ai", "eidos", "health"). Can be changed at any time. Used for display purposes and directory naming conventions. By convention, the directory is named {instance_name}.omnidata.

owner_identity

String or null. Identifies the person or entity that owns this instance. Format is implementation-defined — could be an email address, a username, or a URI. Used for provenance and access control decisions at the application layer.

hat_identifier

String or null. Links this instance to a specific role or “hat” in the ManyHats system. When present, this instance contains knowledge scoped to that role. A person might have director-of-ai.omnidata tied to the director-of-ai hat and health.omnidata tied to the health hat.

description

String or null. Free-form description of the instance’s purpose and scope. Useful for discovery when a user has many instances.

created_at

String (ISO 8601 UTC). Required. Set once at instance creation time.

updated_at

String (ISO 8601 UTC). Required. Refreshed whenever the manifest is modified.

metadata

Object. Optional, defaults to {}. Extensible key-value store for implementation-specific data. Common keys include runtime_version, last_compaction, and migrated_from.

Constraints

The manifest file must contain exactly one JSON object (not an array, not multiple objects). Implementations should validate the manifest on load and reject containers where manifest.json is missing, empty, or malformed.

The instance_id is immutable after creation. Implementations must never overwrite it during updates to other fields. When writing updates, read the existing manifest, merge changes, and write back — preserving instance_id and created_at.

Reading the manifest

import json
from pathlib import Path

container = Path("director-of-ai.omnidata")
manifest = json.loads((container / "manifest.json").read_text())

print(manifest["instance_name"])   # "director-of-ai"
print(manifest["schema_version"])  # 2

Migration from v1

In Schema Version 1, the manifest was stored as a single-row omnidata_manifest SQL table inside the monolithic .omnidata SQLite file. Version 2 extracts this to a standalone JSON file. Migration tooling reads the SQL row, serializes it to JSON, and writes manifest.json to the new directory bundle.