Getting Started¶

Welcome to Synthetic Open Schema! This guide will help you create and run your first synthetic check in under 5 minutes.

What You'll Build¶

A simple HTTP endpoint monitor that:

Checks if an API returns HTTP 200
Validates response time is under 1 second
Runs every 5 minutes

Prerequisites¶

Basic understanding of YAML
A text editor
(Optional) Python 3.11+ to run checks locally

Step 1: Create Your First Check¶

Create a file named my-first-check.yaml:

my-first-check.yaml

apiVersion: v1
kind: HttpCheck
metadata:
  name: my-api-check
  title: My First API Check
  labels:
    environment: production
    team: platform
spec:
  url: https://httpbin.org/status/200
  method: GET
  interval: 5m
  timeout: 30s
  checks:
    - type: statusCode
      value: 200
    - type: responseTime
      operator: lessThan
      value: 1s

Step 2: Understand the Structure¶

Every Synthetic Open Schema check follows this structure:

`apiVersion`¶

Specifies which API version to use: - v1 — Core checks (HTTP, TCP, DNS, TLS, Domain) - browser/v1 — Browser automation checks (Load, Scripted)

`kind`¶

The type of check: - HttpCheck, TcpCheck, DnsCheck, TlsCheck, DomainCheck - LoadCheck, ScriptedCheck

`metadata`¶

Information about the check: - name — Unique identifier (DNS-subdomain format) - title — Human-readable name (optional) - labels — Key-value pairs for organization (optional)

`spec`¶

Check-specific configuration: - Scheduling: interval (e.g., 1m, 5s) or cron expression - Execution: timeout, retries, locations - Notifications: channels for alerting - Assertions: checks array defining success criteria

Step 3: Run Your Check¶

Option A: Using Python Runner¶

Install the runner:

pip install synthetic-open-schema-runner

Run your check:

sos-runner my-first-check.yaml

Expected output:

✓ my-api-check: PASSED
  ✓ statusCode: 200 equals 200
  ✓ responseTime: 245ms lessThan 1s

Duration: 245ms

Step 4: Explore More Check Types¶

Synthetic Open Schema supports 7 check types across two API versions:

Core Checks (v1): - TcpCheck — Monitor TCP port connectivity - DnsCheck — Verify DNS resolution for any record type - TlsCheck — Monitor certificate expiration and validity - DomainCheck — Track domain registration and WHOIS data

Browser Checks (browser/v1): - LoadCheck — Measure real browser page load performance - ScriptedCheck — Execute custom Playwright automation scripts

View complete examples for all check types →

Step 5: Add Assertions¶

Assertions define what "success" means for your check. Different check types support different assertion types:

Numeric Assertions¶

checks:
  - type: statusCode
    value: 200                    # equals
  - type: responseTime
    operator: lessThan
    value: 500ms
  - type: responseTime
    operator: greaterThanOrEqual
    value: 100ms

Operators: equals, notEquals, greaterThan, lessThan, greaterThanOrEqual, lessThanOrEqual

String Assertions¶

checks:
  - type: body
    operator: contains
    value: "success"
  - type: header
    key: Content-Type
    operator: matches
    value: "^application/json"

Operators: equals, notEquals, contains, notContains, matches (regex)

Boolean Assertions¶

checks:
  - type: dnssecEnabled
    value: true
  - type: connect
    value: true

Operators: equals, notEquals

View all assertion types →

Step 6: Schedule Your Checks¶

Interval-Based Scheduling¶

spec:
  interval: 1m      # Every minute
  interval: 30s     # Every 30 seconds
  interval: 1h      # Every hour
  interval: 1d      # Every day

Cron-Based Scheduling¶

spec:
  cron: "0 * * * *"        # Every hour
  cron: "*/5 * * * *"      # Every 5 minutes
  cron: "0 0 * * *"        # Daily at midnight
  cron: "0 9 * * MON-FRI"  # Weekdays at 9am

Note

interval and cron are mutually exclusive. Use one or the other, not both.

Next Steps¶

Learn the Specification¶

See More Examples¶

Build or Integrate¶

View existing implementations

Join the Community¶

Need Help?¶

Ready to monitor? Start writing your checks! 🚀