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.2`	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" | "vue:component" | "vue:composable" | "ts:module" | "node:cli";
  description?: string;
  version: {
    variables: string[];
    hooks: string[];
    components: string[];
    functions: string[];
  };
  logicSignature: {
    props: Record<string, PropSignature>;
    events: Record<string, EventSignature>;
    state: Record<string, StateSignature>;
  };
  exports?: "default" | "named" | { named: string[] };  // Optional export metadata
  style?: StyleMetadata;  // Optional style metadata (when --include-style is used)
  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;
}

interface StyleMetadata {
  styleSources?: StyleSources;
  layout?: LayoutMetadata;
  visual?: VisualMetadata;
  animation?: AnimationMetadata;
  pageLayout?: PageLayoutMetadata;
}

interface StyleSources {
  tailwind?: {
    categories: Record<string, string[]>; // layout, spacing, colors, typography, borders, effects
    breakpoints?: string[]; // sm, md, lg, xl, 2xl
    classCount: number;
  };
  scssModule?: string; // Path to SCSS module file
  scssDetails?: {
    selectors: string[];
    properties: string[];
    features: {
      variables?: boolean;
      nesting?: boolean;
      mixins?: boolean;
    };
  };
  cssModule?: string; // Path to CSS module file
  cssDetails?: {
    selectors: string[];
    properties: string[];
  };
  inlineStyles?: boolean | {
    properties?: string[]; // CSS property names (e.g., ['animationDelay', 'color', 'padding'])
    values?: Record<string, string>; // Property-value pairs for literal values (e.g., { animationDelay: '2s', color: 'blue' })
  };
  styledJsx?: {
    css?: string; // Extracted CSS content from <style jsx> blocks
    global?: boolean; // Whether the style block has global attribute
    selectors?: string[]; // CSS selectors found in the extracted CSS
    properties?: string[]; // CSS properties found in the extracted CSS
  };
  styledComponents?: {
    components?: string[];
    usesTheme?: boolean;
    usesCssProp?: boolean;
  };
  motion?: {
    components?: string[];
    variants?: string[];
    features: {
      gestures?: boolean;
      layoutAnimations?: boolean;
      viewportAnimations?: boolean;
    };
  };
  materialUI?: {
    components?: string[];
    packages?: string[];
    features: {
      usesTheme?: boolean;
      usesSxProp?: boolean;
      usesStyled?: boolean;
      usesMakeStyles?: boolean;
      usesSystemProps?: boolean;
    };
  };
}

interface LayoutMetadata {
  type?: "flex" | "grid" | "relative" | "absolute";
  cols?: string; // Grid column pattern (e.g., "grid-cols-2 md:grid-cols-3")
  hasHeroPattern?: boolean;
  hasFeatureCards?: boolean;
  sections?: string[];
}

interface VisualMetadata {
  colors?: string[]; // Color utility classes (limited to top 10)
  spacing?: string[]; // Spacing utility classes (limited to top 10)
  radius?: string; // Most common border radius pattern
  typography?: string[]; // Typography classes (limited to top 10)
}

interface AnimationMetadata {
  type?: string; // Animation type (e.g., "fade-in", "slide")
  library?: string; // "framer-motion" or "css"
  trigger?: string; // Trigger type (e.g., "inView", "hover")
}

interface PageLayoutMetadata {
  pageRole?: string;
  sections?: string[];
  ctaCount?: number;
}

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
`exports`	`string \| object`	❌	Export metadata: `"default"`, `"named"`, or `{ named: string[] }`
`style`	`StyleMetadata`	❌	Style metadata (only when `--include-style` is used)
`semanticHash`	`string`	✅	Logic-based hash (uif:...)
`fileHash`	`string`	✅	Content-based hash (uif:...)

Style Metadata (Optional)

The style field is only included when using stamp context style or stamp context --include-style. It provides visual and layout information extracted from components.

Style Sources

• tailwind - Utility classes categorized by type
• scssModule / cssModule - Imported style files with parsed details
• inlineStyles - Property names and literal values extracted from style={{...}} objects ✅ v0.3.5
• styledJsx - CSS content, selectors, properties from <style jsx> blocks ✅ v0.3.5
• styledComponents - Styled-components/Emotion usage
• motion - Framer Motion components
• materialUI - Material UI components and features

Layout & Visual

• layout - Flex/grid patterns, hero sections
• visual - Colors, spacing, typography patterns
• animation - Animation library and triggers
• pageLayout - Page-level structure

Note: Style metadata is only included when style information is detected. Components without style usage will not have a style field. See Style Metadata Guide for comprehensive documentation.

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.3.4")
  };
}

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.2`

⚠️ Breaking Change: Schema version 0.2 (v0.3.2+) uses relative paths instead of absolute paths. The projectRootResolved field has been removed. See Migration Guide for details.

interface LogicStampIndex {
  type: "LogicStampIndex";
  schemaVersion: "0.2";
  projectRoot: string;              // Relative path (always "." in v0.3.2+)
  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.json

The 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.

Schema Versions

UIFContract Schema

Schema Version: `0.3`

Style Metadata (Optional)

Style Sources

Layout & Visual

LogicStampBundle Schema

Schema Version: `0.1`

LogicStampIndex Schema

Schema Version: `0.2`

Hash Formats

Semantic Hash (`semanticHash`)

File Hash (`fileHash`)

Bundle Hash (`bundleHash`)

Validation

Schema Evolution

Major version changes

Minor version changes

Patch version changes

Product

Contact

Legal

Schema Reference

Schema Versions

UIFContract Schema

Schema Version: 0.3

Style Metadata (Optional)

Style Sources

Layout & Visual

LogicStampBundle Schema

Schema Version: 0.1

LogicStampIndex Schema

Schema Version: 0.2

Hash Formats

Semantic Hash (semanticHash)

File Hash (fileHash)

Bundle Hash (bundleHash)

Validation

Schema Evolution

Major version changes

Minor version changes

Patch version changes

Schema Version: `0.3`

Schema Version: `0.1`

Schema Version: `0.2`

Semantic Hash (`semanticHash`)

File Hash (`fileHash`)

Bundle Hash (`bundleHash`)