Skip to content

Specification Overview

The Synthetic Open Schema specification defines a vendor-neutral format for synthetic monitoring checks. This page provides an overview of the specification structure and how to navigate it.

API Versions

Synthetic Open Schema uses semantic API versioning:

v1 — Core Checks (Stable)

Declarative checks with assertion-based validation:

Status: ✅ Stable (v1.0.0 released 2026-02-07)

View v1 API documentation →

browser/v1 — Browser Checks (Stable)

Programmatic browser automation checks:

Status: ✅ Stable (v1.0.0 released 2026-02-07)

View browser/v1 API documentation →

Specification Structure

Core Documents

Document Description
Base Model Resource structure (apiVersion, kind, metadata, spec)
Common Types Shared fields, assertion types, operators, validation rules

Check Kind Specifications

Each check kind has its own specification document:

  • Fields: Required and optional fields for the check
  • Assertions: Supported assertion types for validation
  • Examples: Complete YAML examples
  • Conformance: Requirements for implementations

Policy Documents

Document Description
Glossary Terminology and definitions
Versioning API versioning strategy
Compatibility Backward/forward compatibility guarantees

Resource Model

All checks follow a Kubernetes-style resource structure:

apiVersion: v1              # or browser/v1
kind: HttpCheck             # Check type
metadata:
  name: my-check            # Unique identifier
  title: My Check           # Human-readable name (optional)
  labels:                   # Key-value pairs (optional)
    env: production
spec:
  # Check-specific configuration
  url: https://example.com
  interval: 1m
  checks:
    - type: statusCode
      value: 200

Key Concepts

  • apiVersion: Declares which API version the check uses
  • kind: Specifies the check type (e.g., HttpCheck, DnsCheck)
  • metadata: Information about the check (name, labels, etc.)
  • spec: Check-specific configuration and assertions

Learn more about the base model →

Common Fields

All check kinds share these fields in their spec:

Scheduling (Mutually Exclusive)

Interval-based: 

spec:
  interval: 1m  # Every minute

Cron-based: 

spec:
  cron: "*/5 * * * *"  # Every 5 minutes

Execution

spec:
  timeout: 30s              # Maximum execution time
  retries: 3                # Number of retry attempts
  retryDelay: 5s            # Delay between retries
  locations:                # Execution locations
    - us-east-1
    - eu-west-1

Notifications

spec:
  channels:                 # Notification channels
    - slack-alerts
    - pagerduty-critical

Assertions

spec:
  checks:                   # Success criteria
    - type: statusCode
      value: 200
    - type: responseTime
      operator: lessThan
      value: 500ms

View complete common fields documentation →

Assertion Types

Synthetic Open Schema supports five assertion types, each with specific operators and value formats:

  • Numeric — Status codes, response times, counts (operators: equals, greaterThan, lessThan, etc.)
  • String — Body content, headers, DNS records (operators: equals, contains, matches, etc.)
  • Boolean — Binary states like connected, valid, enabled (operators: equals, notEquals)
  • Time-based — Dates, expirations, durations (operators: same as numeric)
  • List — DNS records, nameservers, arrays (operators: contains, containsAny, containsAll)

View complete assertion documentation with examples →

Conformance

An implementation claiming compatibility with Synthetic Open Schema MUST:

  1. Implement the base Resource model as defined in check.md
  2. Support at least one check kind fully
  3. Reject configurations that violate normative constraints
  4. Clearly document which check kinds and features are supported
  5. Handle scheduling (interval or cron) as specified
  6. Evaluate assertions according to the specification

Implementations SHOULD:

  • Support all stable check kinds
  • Provide clear error messages for validation failures
  • Support multiple execution locations
  • Implement retry logic

Learn more about conformance requirements →

Examples

Complete, tested YAML example configurations are available in the model repository:

Core Checks (v1):

Browser Checks (browser/v1):

View all examples →

JSON Schema

JSON Schema definitions for validation and tooling integration are published at:

📦 https://github.com/syntheticopenschema/schemas

These schemas are generated from the reference Python implementation and updated with each release.

Contributing

To propose changes to the specification:

  1. Open an issue describing the proposed change
  2. Submit a pull request with specification updates
  3. Update examples and schemas accordingly
  4. Ensure backward compatibility (or document breaking change)

Read the contribution guidelines →

Governance

The specification follows an open governance model:

  • Steward: Ideatives Inc.
  • Maintainer: @dmonroy
  • RFC Process: New check types require 14-day community review
  • Decision Process: Documented in GOVERNANCE.md

Learn more about governance →

Support