Schema Language

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:

@0xb2a3f4c5d6e7f8a9;  # Unique file ID

# Annotations for code generation
using Go = import "/go.capnp";
$Go.package("zap");
$Go.import("github.com/zap-protocol/zap-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:

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:

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:

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

Lists

Homogeneous collections:

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

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

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

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:

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:

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:

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:

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:

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

Deprecation

Mark fields as deprecated (still readable):

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

Code Generation

Generate code for your language:

# 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 for language-specific details.

Complete Schema Reference

The complete ZAP schema is available at:

GitHub: zap.capnp

Key sections:

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

Schema Language

On this page