Skip to main content
The schema is still in active development, and subject to change.

​
Overview

Predicate files use XML format with a .predicate extension to store AI agent decisions alongside your code. These files capture not just what decisions were made, but the reasoning and context behind them.

​
File Structure

Predicate files are stored as hidden files in the same directory as their associated source code: 
src/
├── extension.ts
└── .extension.ts.predicate

​
Schema Definition

The Predicate schema defines four main sections within the root element:
​
predicate
root element
required
Root element for all predicate files.Attributes:
  • version (required): Schema version (currently “1.0”)
  • xmlns:xsi: XML Schema instance namespace
  • xsi:schemaLocation: Schema validation URL
<predicate version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="https://predicate.sh/schema/v1 https://predicate.sh/schema/v1/predicate.xsd">

​
1. Metadata

Contains basic file information and timestamps:
​
sourceFile
string
required
Path to the source file this predicate documents
​
lastModified
ISO 8601 datetime
required
Timestamp of last modification
​
author
string
Author of the predicate (typically “AI Assistant”)
​
description
string
Brief description of the source file’s purpose
<metadata>
  <sourceFile>src/extension.ts</sourceFile>
  <lastModified>2024-01-15T10:30:00Z</lastModified>
  <author>AI Assistant</author>
  <description>VSCode extension entry point</description>
</metadata>

​
2. Decisions

The core of each predicate file, containing three levels of detail:
​
oneLiner
string
required
Brief summary of the file’s purpose. Maximum 150 characters.
<oneLiner>Main extension entry point that registers commands and providers</oneLiner>
​
short
string
required
Key decisions and architecture overview. Maximum 500 characters.
<short>Registers predicate tree view, file creation commands, and MCP server. Uses dependency injection pattern for extensibility.</short>
​
long
CDATA
required
Detailed explanations with full markdown support. Supports format attribute for content type.Attributes:
  • format: markdown | plain | html (default: markdown)
<long format="markdown"><![CDATA[
## Architecture Overview

This file serves as the main entry point for the VSCode extension, implementing:

- **Command Registration**: All extension commands are registered here
- **Provider Setup**: Tree data providers and content providers are initialized
- **Dependency Injection**: Services are configured for easy testing and extension
]]></long>

​
3. Context

Structured metadata about technical decisions:
​
frameworks
array
List of frameworks or technologies used in the file.
<frameworks>
  <framework>vscode-extension-api</framework>
  <framework>typescript</framework>
</frameworks>
​
patterns
array
Design patterns or architectural patterns implemented.
<patterns>
  <pattern>dependency-injection</pattern>
  <pattern>command-pattern</pattern>
</patterns>
​
dependencies
array
External dependencies or packages used.
<dependencies>
  <dependency>@vscode/extension-api</dependency>
</dependencies>
​
alternatives
array
Alternative approaches that were considered.
<alternatives>
  <alternative>Direct instantiation vs dependency injection</alternative>
</alternatives>
​
tradeoffs
array
Tradeoffs made in the implementation decisions.
<tradeoffs>
  <tradeoff>Added complexity for better testability</tradeoff>
</tradeoffs>

​
4. Relationships

Define connections between files:
​
relationship
object
Individual relationship to another file in the codebase.Attributes:
  • target (required): Path to the related file
  • type (required): Type of relationship (see relationship types below)
Content: Description of the relationship
<relationships>
  <relationship target="src/providers/TreeDataProvider.ts" type="depends_on">
    Uses for predicate tree view functionality
  </relationship>
  <relationship target="src/commands/CreatePredicate.ts" type="imports">
    Imports command implementations
  </relationship>
</relationships>

​
Relationship Types

The schema supports 12 relationship types:
TypeDescription
depends_onFile depends on target functionality
influencesChanges here may affect target
related_toGeneral relationship or similarity
supersedesReplaces or makes target obsolete
blocksPrevents target from functioning
implementsProvides implementation for target interface
usesUtilizes target functionality
importsExplicitly imports from target
extendsInherits from or builds upon target
configuresSets up or configures target
testsContains tests for target
documentsProvides documentation for target

​
Tags

​
tag
string
Categorization tags for the file. Each tag must follow specific formatting rules.Requirements:
  • 2-30 characters
  • Alphanumeric with hyphens and underscores only
  • No spaces or special characters
<tags>
  <tag>entry-point</tag>
  <tag>vscode-extension</tag>
  <tag>command-registration</tag>
</tags>

​
Content Formats

The schema supports three content formats:
  • markdown - Full markdown syntax (default for long sections)
  • plain - Plain text
  • html - HTML markup

​
Complete Example

Here’s a complete predicate file example: 
<?xml version="1.0" encoding="UTF-8"?>
<predicate version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="https://predicate.sh/schema/v1 https://predicate.sh/schema/v1/predicate.xsd">
  
  <metadata>
    <sourceFile>src/extension.ts</sourceFile>
    <lastModified>2024-01-15T10:30:00Z</lastModified>
    <author>AI Assistant</author>
    <description>VSCode extension entry point</description>
  </metadata>
  
  <decisions>
    <oneLiner>Main extension entry point that registers commands and providers</oneLiner>
    
    <short>Registers predicate tree view, file creation commands, and MCP server. Uses dependency injection for extensibility and testing.</short>
    
    <long format="markdown"><![CDATA[
    ## Architecture Overview
    
    This file serves as the main entry point for the VSCode extension, implementing:
    
    - **Command Registration**: All extension commands registered in `activate()`
    - **Provider Setup**: Tree data providers and content providers initialized
    - **Service Configuration**: Dependency injection container setup
    
    The choice of dependency injection over direct instantiation provides better testability at the cost of some additional complexity.
    ]]></long>
    
    <context>
      <frameworks>
        <framework>vscode-extension-api</framework>
        <framework>typescript</framework>
      </frameworks>
      <patterns>
        <pattern>dependency-injection</pattern>
        <pattern>command-pattern</pattern>
      </patterns>
      <dependencies>
        <dependency>@vscode/extension-api</dependency>
      </dependencies>
      <alternatives>
        <alternative>Direct instantiation vs dependency injection</alternative>
      </alternatives>
      <tradeoffs>
        <tradeoff>Added complexity for better testability</tradeoff>
      </tradeoffs>
    </context>
  </decisions>
  
  <relationships>
    <relationship target="src/providers/TreeDataProvider.ts" type="depends_on">
      Uses for predicate tree view functionality
    </relationship>
    <relationship target="src/commands/CreatePredicate.ts" type="imports">
      Imports command implementations
    </relationship>
  </relationships>
  
  <tags>
    <tag>entry-point</tag>
    <tag>vscode-extension</tag>
    <tag>command-registration</tag>
  </tags>
  
</predicate>

​
Validation

The schema is defined in XSD format and available at: 
https://predicate.sh/schema/v1/predicate.xsd
This enables XML validation in editors and automated tooling to ensure predicate files conform to the expected structure.