Skip to main content
The schema command outputs the JSON schema definition for Retis event files.

​
Usage

retis schema

​
Overview

This command prints the complete JSON schema that describes the structure of events produced by Retis. The schema can be used for:
  • Understanding event structure
  • Validating event files
  • Generating code for parsing events
  • Documentation purposes
  • IDE autocomplete and validation

​
Examples

# Display schema in terminal
retis schema

​
Schema Structure

The schema describes all possible event sections: 
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Event",
  "type": "object",
  "properties": {
    "common": { ... },
    "kernel": { ... },
    "packet": { ... },
    "skb": { ... },
    "skb_tracking": { ... },
    "ct": { ... },
    "dev": { ... },
    "netns": { ... },
    "ovs": { ... },
    "nft": { ... },
    "skb_drop": { ... }
  }
}

​
Event Sections

The schema defines these event sections:

​
Common Section

"common": {
  "timestamp": "integer",
  "smp_id": "integer",
  "task": {
    "pid": "integer",
    "tgid": "integer",
    "comm": "string"
  }
}

​
Kernel Section

"kernel": {
  "symbol": "string",
  "probe_type": "string"
}

​
Packet Section

"packet": {
  "data": "array of integers",
  "len": "integer"
}

​
SKB Tracking Section

"skb_tracking": {
  "orig_head": "integer",
  "timestamp": "integer",
  "skb": "integer"
}

​
Other Sections

See the full schema output for details on:
  • skb - Socket buffer metadata
  • ct - Conntrack information
  • dev - Network device data
  • netns - Namespace information
  • ovs - OpenVSwitch events
  • nft - Nftables context
  • skb_drop - Drop reasons

​
Use Cases

​
Generate parsing code

# Use with code generators
retis schema > schema.json
quicktype schema.json -o event_types.py

​
Validate event files

# Validate events against schema
retis schema > schema.json
retis print --format json events.data > events.json
jsonschema -i events.json schema.json

​
IDE integration

# Save schema for IDE autocomplete
retis schema > .retis-event-schema.json
Configure your IDE to use the schema for JSON files.

​
Documentation

# Generate documentation from schema
retis schema | json-schema-to-markdown > event-docs.md

​
Schema Format

The output follows JSON Schema Draft 7 specification. Key features:
  • Type definitions for all fields
  • Required vs optional fields
  • Nested object structures
  • Array types and constraints
  • Enumerations for fixed values

​
Integration Examples

​
Python with jsonschema

import json
import jsonschema

# Load schema
with open('schema.json') as f:
    schema = json.load(f)

# Load event
with open('event.json') as f:
    event = json.load(f)

# Validate
try:
    jsonschema.validate(event, schema)
    print("Event is valid")
except jsonschema.ValidationError as e:
    print(f"Invalid event: {e}")

​
TypeScript type generation

# Generate TypeScript types
retis schema > schema.json
json2ts schema.json > event.types.ts

​
Go struct generation

# Generate Go structs
retis schema > schema.json
schema-generate schema.json --package events > events.go

​
Schema Versioning

The schema corresponds to the Retis version that generated it. When:
  • Reading old event files with new Retis versions
  • Sharing event files between different Retis versions
  • Archiving events for long-term storage
Save the schema alongside your event files: 
retis collect -o events.data
retis schema > events-schema.json

​
JSON Output Format

The schema is output as formatted JSON: 
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Event",
  "description": "A Retis event containing network tracing data",
  "type": "object",
  "properties": {
    ...
  }
}

​
Common Use Cases

​
Reference documentation

# Keep schema as reference
retis schema > SCHEMA.json
git add SCHEMA.json

​
CI/CD validation

#!/bin/bash
# Validate test output in CI
retis schema > /tmp/schema.json
retis collect --cmd "run_test.sh" -o /tmp/events.data
retis print /tmp/events.data > /tmp/events.json
jsonschema -i /tmp/events.json /tmp/schema.json

​
API development

# Generate API types from schema
retis schema | openapi-generator generate -g typescript-fetch

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us