# Schema Language

URL: https://docs.hanzo.ai/docs/zap/schema

> Cap'n Proto schema reference for ZAP

ZAP uses Cap'n Proto schemas to define messages and interfaces. This page covers the schema language basics and ZAP-specific patterns.

## Schema Basics

### File Structure

Every Cap'n Proto schema file starts with a unique ID:

```c
@0xb2a3f4c5d6e7f8a9;  # Unique file ID

# Annotations for code generation
using Go = import "/go.capnp";
$Go.package("zap");
$Go.import("github.com/zap-proto/go");
```

### Primitive Types

| Type             | Description       | Size       |
| ---------------- | ----------------- | ---------- |
| `Void`           | Empty type        | 0 bits     |
| `Bool`           | Boolean           | 1 bit      |
| `Int8/16/32/64`  | Signed integers   | 8-64 bits  |
| `UInt8/16/32/64` | Unsigned integers | 8-64 bits  |
| `Float32/64`     | IEEE 754 floats   | 32/64 bits |
| `Text`           | UTF-8 string      | pointer    |
| `Data`           | Raw bytes         | pointer    |

### Structs

Structs define composite data types:

```c
struct Timestamp {
  seconds @0 :Int64;
  nanos @1 :UInt32;
}

struct Metadata {
  entries @0 :List(Entry);

  struct Entry {
    key @0 :Text;
    value @1 :Text;
  }
}
```

Field numbers (`@0`, `@1`, etc.) define wire format order and enable schema evolution.

### Enums

Enumerations for fixed value sets:

```c
enum LogLevel {
  debug @0;
  info @1;
  warn @2;
  error @3;
}

enum Transport {
  stdio @0;
  http @1;
  websocket @2;
  zap @3;
  unix @4;
}
```

### Unions

Tagged unions for variant types:

```c
struct ResourceContent {
  uri @0 :Text;
  mimeType @1 :Text;
  content :union {
    text @2 :Text;
    blob @3 :Data;
  }
}
```

### Lists

Homogeneous collections:

```c
struct ToolList {
  tools @0 :List(Tool);
}

struct PromptMessage {
  role @0 :Role;
  content @1 :Content;

  enum Role {
    user @0;
    assistant @1;
    system @2;
  }
}
```

## ZAP Core Types

### Tool Definitions

```c
struct Tool {
  name @0 :Text;
  description @1 :Text;
  schema @2 :Data;  # JSON Schema as bytes
  annotations @3 :Metadata;
}

struct ToolCall {
  id @0 :Text;
  name @1 :Text;
  args @2 :Data;  # JSON arguments as bytes
  metadata @3 :Metadata;
}

struct ToolResult {
  id @0 :Text;
  content @1 :Data;  # Result content as bytes
  error @2 :Text;
  metadata @3 :Metadata;
}
```

### Resource Definitions

```c
struct Resource {
  uri @0 :Text;
  name @1 :Text;
  description @2 :Text;
  mimeType @3 :Text;
  annotations @4 :Metadata;
}

struct ResourceContent {
  uri @0 :Text;
  mimeType @1 :Text;
  content :union {
    text @2 :Text;
    blob @3 :Data;
  }
}
```

### Prompt Definitions

```c
struct Prompt {
  name @0 :Text;
  description @1 :Text;
  arguments @2 :List(Argument);

  struct Argument {
    name @0 :Text;
    description @1 :Text;
    required @2 :Bool;
  }
}

struct PromptMessage {
  role @0 :Role;
  content @1 :Content;

  enum Role {
    user @0;
    assistant @1;
    system @2;
  }

  struct Content {
    union {
      text @0 :Text;
      image @1 :ImageContent;
      resource @2 :ResourceContent;
    }
  }
}
```

## Interfaces

### Defining Interfaces

Interfaces define RPC methods:

```c
interface Zap {
  init @0 (client :ClientInfo) -> (server :ServerInfo);
  listTools @1 () -> (tools :ToolList);
  callTool @2 (call :ToolCall) -> (result :ToolResult);
  listResources @3 () -> (resources :ResourceList);
  readResource @4 (uri :Text) -> (content :ResourceContent);
  subscribe @5 (uri :Text) -> (stream :ResourceStream);
  listPrompts @6 () -> (prompts :PromptList);
  getPrompt @7 (name :Text, args :Metadata) -> (messages :List(PromptMessage));
  log @8 (level :LogLevel, message :Text, data :Data);
}
```

### Interface Inheritance

Interfaces can extend others:

```c
interface Gateway extends(Zap) {
  addServer @0 (name :Text, url :Text, config :ServerConfig) -> (id :Text);
  removeServer @1 (id :Text) -> ();
  listServers @2 () -> (servers :List(ConnectedServer));
  serverStatus @3 (id :Text) -> (status :ServerStatus);
}
```

### Streaming Interfaces

Return capability objects for streaming:

```c
interface ResourceStream {
  next @0 () -> (content :ResourceContent, done :Bool);
  cancel @1 () -> ();
}
```

## Schema Evolution

Cap'n Proto schemas support forward/backward compatible evolution:

### Adding Fields

Add new fields with higher ordinals:

```c
struct Tool {
  name @0 :Text;
  description @1 :Text;
  schema @2 :Data;
  annotations @3 :Metadata;
  version @4 :Text;  # New field - old readers ignore
}
```

### Default Values

Provide defaults for new fields:

```c
struct ServerConfig {
  transport @0 :Transport;
  auth @1 :Auth;
  timeout @2 :UInt32 = 30000;  # Default 30 seconds
}
```

### Deprecation

Mark fields as deprecated (still readable):

```c
struct OldStruct {
  oldField @0 :Text $deprecated;  # Annotation
  newField @1 :Text;
}
```

## Code Generation

Generate code for your language:

```bash
# Rust
capnp compile -o rust zap.capnp

# Go
capnp compile -o go zap.capnp

# C++
capnp compile -o c++ zap.capnp

# Python (pycapnp)
capnp compile -o pycapnp zap.capnp
```

See [Language Bindings](https://docs.hanzo.ai/docs/zap/bindings) for language-specific details.

## Complete Schema Reference

The complete ZAP schema is available at:

- [GitHub: zap.capnp](https://github.com/zap-proto/zap/blob/main/schema/zap.capnp)

Key sections:

- Core types (Timestamp, Metadata)
- Tool/Resource/Prompt definitions
- Zap/Gateway/Coordinator interfaces
- Post-quantum cryptography types
- Corona consensus types
- Agent consensus types
- W3C DID types

- [Overview](https://docs.hanzo.ai/docs/zap/overview): Understanding ZAP architecture and core concepts
- [Getting Started](https://docs.hanzo.ai/docs/zap/getting-started): Install ZAP and build your first AI agent
- [Protocol Specification](https://docs.hanzo.ai/docs/zap/protocol): ZAP wire format, encoding, and RPC semantics
- [The Local Router](https://docs.hanzo.ai/docs/zap/router): One ZAP router per user, embedded in every process that speaks ZAP — no daemon
- [Language Bindings](https://docs.hanzo.ai/docs/zap/bindings): ZAP SDK documentation for all supported languages
- [Advanced Topics](https://docs.hanzo.ai/docs/zap/advanced): Post-quantum cryptography, consensus, identity, and blockchain integration