restraml

tikoci.github.io/restraml — schema downloads, side-by-side version diffs, an interactive API explorer, a command lookup tool, and a browser-based /app YAML editor for the MikroTik RouterOS REST API. No install needed, runs in your browser.

For RouterOS 7.22+: JSON Schema files for /app container YAML are also published there, ready to plug into VSCode — setup details below.

Auto-generated API schemas for the MikroTik RouterOS REST API, built automatically by GitHub Actions — you can watch the sausage being made.

Pre-built schema files for the RouterOS REST API are available at https://tikoci.github.io/restraml/

Each RouterOS version includes:

• RAML — RAML 1.0 schema, usable in Postman, MuleSoft, and other API tools
• OpenAPI 3 — OpenAPI 3.0 schema (7.21.1+), viewable in the API Explorer with enriched descriptions from MikroTik documentation
• JSON — raw /console/inspect output from RouterOS, useful for data analysis and diffs
• MIB — link to the official MikroTik MIB for SNMP

There may be a base and +extra download for each version:

• base — just the routeros.npk system package
• +extra — all x86 packages: routeros, dude, container, rose-storage, gps, lora, calea, user-manager, ups, iot, wifiwave2, tr069-client

An interactive API explorer at tikoci.github.io/restraml/openapi.html lets you browse the RouterOS REST API using the OpenAPI 3 schema. Powered by Scalar, it provides endpoint documentation enriched with descriptions from MikroTik's official documentation, request/response examples, and a built-in HTTP client for testing.

The project website includes a diff tool that compares the /console/inspect output between any two RouterOS versions — useful for tracking new commands, removed attributes, and API changes across releases.

A command lookup tool at tikoci.github.io/restraml/lookup.html lets you search RouterOS commands and attributes across versions, with filtering by path and attribute name.

A browser-based YAML editor at tikoci.github.io/restraml/tikapp.html lets you write and validate RouterOS /app YAML directly in your browser using Monaco editor (the same editor that powers VS Code). Features include:

• Schema validation against any versioned schema (7.22+) or the latest schema
• Built-in examples from MikroTik's app library, filterable by category
• Dirty-state tracking — edit examples safely with Stash / Recall / Discard workflow
• app-store-urls= toggle that auto-converts single app ↔ array format
• Custom YAML autosaved to browser local storage (restored on reload)
• Support for both single /app definitions and app-store-urls= array format
• Download as .tikapp.yaml / .tikappstore.yaml, or copy YAML to clipboard
• Copy directly as a RouterOS /app add yaml= command
• Shareable URLs — version, schema mode, and YAML content encoded on explicit Share

📖 Full user manual →

RouterOS 7.22+ includes /app — a YAML format (similar to docker-compose but RouterOS-specific) for defining custom container applications. This project provides JSON Schema files to validate /app YAML in editors like VSCode.

Per-version schemas are automatically validated against MikroTik's built-in /app entries for each new RouterOS release to verify accuracy.

Install the Red Hat YAML extension for VSCode, then use either approach:

Add a yaml-language-server comment at the top of your YAML file. The YAML extension will detect it automatically — no settings changes needed.

For a single /app definition:

# yaml-language-server: $schema=https://tikoci.github.io/restraml/routeros-app-yaml-schema.latest.json

name: my-app
descr: My custom RouterOS app
services:
  server:
    image: myimage:latest
    ports:
      - 8080:80:web

For an app store file (array of /app definitions, used with app-store-urls=):

# yaml-language-server: $schema=https://tikoci.github.io/restraml/routeros-app-yaml-store-schema.latest.json

- name: app-one
  services:
    server:
      image: app1:latest
- name: app-two
  services:
    server:
      image: app2:latest

Add to your .vscode/settings.json to apply the schema automatically to any file whose name matches the glob pattern. Files must be named using the configured ending (e.g. my-app.tikapp.yaml for a single /app definition, or my-store.tikappstore.yaml for a store file):

{
  "yaml.schemas": {
    "https://tikoci.github.io/restraml/routeros-app-yaml-schema.latest.json": "*.tikapp.yaml",
    "https://tikoci.github.io/restraml/routeros-app-yaml-store-schema.latest.json": "*.tikappstore.yaml"
  }
}

The RAML 1.0 schema can be imported into Postman (download here) to explore the RouterOS REST API:

1. Copy the URL of the version-specific RAML file from the Schema Downloads table (right-click the base or +extra link under RAML)
2. In Postman, go to File → Import and paste the URL
3. On the next screen, select Postman Collection — note this may take several minutes for the full schema

restraml/
├── rest2raml.js              # Main script: RouterOS REST API → RAML 1.0
├── validraml.cjs             # RAML 1.0 validator
├── appyamlvalidate.js        # /app YAML schema validator (Bun)
├── deep-inspect.ts           # Deep API tree inspection (Bun)
├── ros-api-protocol.ts       # Vendored RouterOS native API wire protocol
├── enrich-openapi.ts         # Enriches OpenAPI schemas with descriptions
├── validate-openapi.ts       # OpenAPI 3.0 schema validator
├── *.test.ts                 # Unit + integration tests (bun test)
├── Dockerfile.chr-qemu       # Local dev: RouterOS CHR in QEMU via Docker
├── scripts/
│   ├── entrypoint.sh         # QEMU launcher for local Docker use
│   ├── test-with-qemu.sh     # Integration tests (deep-inspect) against local CHR
│   ├── test-ros-api.sh       # Integration + stress tests (ros-api-protocol) against local CHR
│   └── benchmark-qemu.sh     # REST vs native API benchmark suite against local CHR
├── docs/                     # GitHub Pages root (one subdirectory per version)
│   ├── index.html            # Main website: version list, diff tool, downloads
│   ├── openapi.html          # Interactive API Explorer (Scalar-based)
│   ├── lookup.html           # Command search tool
│   ├── diff.html             # Schema diff tool
│   ├── tikapp.html           # /app YAML editor (Monaco-based)
│   ├── routeros-app-yaml-schema.latest.json
│   ├── routeros-app-yaml-store-schema.latest.json
│   └── {version}/            # Per-version schemas (RAML, OpenAPI 3, inspect JSON)
├── CLAUDE.md                 # Full architecture guide for AI agents
├── AGENTS.md                 # GitHub Copilot agent instructions
└── .github/workflows/
    ├── auto.yaml             # Daily cron: detect new versions, trigger builds
    ├── manual-using-docker-in-docker.yaml
    ├── manual-using-extra-docker-in-docker.yaml
    ├── appyamlschemas.yaml   # Validate and publish /app YAML schemas
    └── manual-from-secrets.yaml

For full architecture details, CI/CD pipeline documentation, and development instructions, see:

• CLAUDE.md — comprehensive architecture guide
• AGENTS.md — GitHub Copilot agent instructions