Schema Reference
Schema Reference
Complete schema reference for all LogicStamp data structures. All schemas are versioned and validated to ensure compatibility.
Schema Versions
LogicStamp uses semantic versioning for schemas:
| Schema | Current Version | Purpose |
|---|---|---|
UIFContract | 0.3 | Component contract structure |
LogicStampBundle | 0.1 | LLM context bundle format |
LogicStampIndex | 0.1 | Main index for multi-file context |
UIFContract Schema
Component contract structure embedded in bundles.
Schema Version: 0.3
interface UIFContract {
type: "UIFContract";
schemaVersion: "0.3";
kind: "react:component" | "react:hook" | "typescript:module";
description?: string;
version: {
variables: string[];
hooks: string[];
components: string[];
functions: string[];
};
logicSignature: {
props: Record<string, PropSignature>;
events: Record<string, EventSignature>;
state: Record<string, StateSignature>;
};
semanticHash: string; // Format: "uif:..." (24 hex chars)
fileHash: string; // Format: "uif:..." (24 hex chars)
}
interface PropSignature {
type: string;
signature?: string; // For function props
optional?: boolean;
}
interface EventSignature {
type: string;
signature?: string; // Function signature
}
interface StateSignature {
type: string;
}| Field | Type | Required | Description |
|---|---|---|---|
type | "UIFContract" | ✅ | Contract type identifier |
schemaVersion | "0.3" | ✅ | Schema version for compatibility |
kind | string | ✅ | Component type (react:component, react:hook, etc.) |
description | string | ❌ | Human-readable description |
version | object | ✅ | Structural composition |
logicSignature | object | ✅ | Public API contract |
semanticHash | string | ✅ | Logic-based hash (uif:...) |
fileHash | string | ✅ | Content-based hash (uif:...) |
LogicStampBundle Schema
LLM context bundle containing a dependency graph and contracts.
Schema Version: 0.1
interface LogicStampBundle {
$schema?: string; // Optional JSON Schema reference
position?: string; // Human-readable position (e.g., "1/5")
type: "LogicStampBundle";
schemaVersion: "0.1";
entryId: string; // Path to root component
depth: number; // Dependency traversal depth
createdAt: string; // ISO 8601 timestamp
bundleHash: string; // Format: "uifb:..." (24 hex chars)
graph: {
nodes: BundleNode[];
edges: BundleEdge[];
};
meta: {
missing: MissingDependency[];
source: string; // Tool version (e.g., "logicstamp-context@0.1.0")
};
}
interface BundleNode {
entryId: string;
contract: UIFContract;
codeHeader?: string; // @uif header block (if --include-code header)
}
interface BundleEdge {
[0]: string; // Source entryId
[1]: string; // Target entryId
}
interface MissingDependency {
name: string;
reason: "external package" | "file not found" | "outside scan path" | "max depth exceeded" | "circular dependency";
referencedBy: string; // Component that imports it
}LogicStampIndex Schema
Main index file for multi-file context organization.
Schema Version: 0.1
interface LogicStampIndex {
type: "LogicStampIndex";
schemaVersion: "0.1";
projectRoot: string; // Relative path (usually ".")
projectRootResolved: string; // Absolute path
createdAt: string; // ISO 8601 timestamp
summary: {
totalComponents: number;
totalBundles: number;
totalFolders: number;
totalTokenEstimate: number;
};
folders: FolderEntry[];
meta: {
source: string; // Tool version
};
}
interface FolderEntry {
path: string; // Relative path from project root
contextFile: string; // Path to this folder's context.json
bundles: number; // Number of bundles in this folder
components: string[]; // Component file names
isRoot: boolean; // Whether this is an entry point
rootLabel?: string; // Label for root folders
tokenEstimate: number; // Estimated token count
}Hash Formats
All hashes in LogicStamp follow consistent formats:
Semantic Hash (semanticHash)
- Format:
uif:+ 24 hex characters - Example:
uif:1a27d0944bbaaf561ee05a01 - Based on: Component logic and contract structure
- Changes when: Props, events, state, or structural footprint changes
File Hash (fileHash)
- Format:
uif:+ 24 hex characters - Example:
uif:1f0fa0e2c8958d7fc1696036 - Based on: Raw file content (excluding @uif headers)
- Changes when: Any file content modification
Bundle Hash (bundleHash)
- Format:
uifb:+ 24 hex characters - Example:
uifb:abc123e4f99aa01deef02bb1 - Based on: Bundle structure (nodes, depth, schema version)
- Changes when: Any component's semantic hash changes, or bundle structure changes
See HASHES.md for detailed information about hash computation.
Validation
All schemas can be validated using stamp context validate:
# Validate all context files (multi-file mode)
stamp context validate
# Validate a specific file
stamp context validate src/components/context.jsonThe validator checks:
- Required fields are present
- Field types match schema
- Schema versions are correct
- Hash formats are valid
- Structure matches expected shape
Schema Evolution
Schemas are versioned to support evolution:
Major version changes
Breaking changes requiring migration
Minor version changes
New optional fields, backward compatible
Patch version changes
Bug fixes, fully backward compatible
When schema versions change: Old versions remain supported for reading, new versions are generated for writing, and validation warns on unexpected versions.