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

interface UIFContract {
  type: "UIFContract";
  schemaVersion: "0.4";
  kind: "react:component" | "react:hook" | "vue:component" | "vue:composable" | "ts:module" | "node:cli";
  description?: string;
  composition: {
    variables: string[];
    hooks: string[];
    components: string[];
    functions: string[];
  };
  interface: {
    props: Record<string, PropSignature>;
    emits: 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.4"`	✅	Schema version for compatibility
`kind`	`string`	✅	Component type (react:component, react:hook, etc.)
`description`	`string`	❌	Human-readable description
`composition`	`object`	✅	Structural composition
`interface`	`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.6.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.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.

Next Steps

Explore UIF contracts or check out the complete reference for all features.

UIF Contracts Complete Reference GitHub Repository

Schema Versions

UIFContract Schema

Schema Version: `0.4`

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

Next Steps

Product

Resources

Organization

Legal

Schema Reference

Schema Versions

UIFContract Schema

Schema Version: 0.4

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

Next Steps

Schema Version: `0.4`

Schema Version: `0.1`

Schema Version: `0.2`

Semantic Hash (`semanticHash`)

File Hash (`fileHash`)

Bundle Hash (`bundleHash`)