Voiden · Schema

Voiden .void File

Schema for Voiden .void files — plain Markdown documents with YAML frontmatter and structured API request blocks that combine documentation and executable HTTP requests.

API DesignAPI TestingAPI DocumentationDeveloper ToolsGit NativeMarkdown

Properties

Name	Type	Description
version	string	The Voiden file format version.
name	string	Human-readable name for this .void file or block collection.
description	string	Documentation describing the purpose of this file.
blocks	array	Array of reusable blocks defined in this file.
imports	array	Other .void files imported to inherit blocks from.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "$id": "https://voiden.md/schemas/void-file",
  "title": "Voiden .void File",
  "description": "Schema for Voiden .void files — plain Markdown documents with YAML frontmatter and structured API request blocks that combine documentation and executable HTTP requests.",
  "type": "object",
  "properties": {
    "version": {
      "type": "string",
      "description": "The Voiden file format version.",
      "example": "1.0"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for this .void file or block collection."
    },
    "description": {
      "type": "string",
      "description": "Documentation describing the purpose of this file."
    },
    "blocks": {
      "type": "array",
      "description": "Array of reusable blocks defined in this file.",
      "items": {
        "$ref": "#/$defs/Block"
      }
    },
    "imports": {
      "type": "array",
      "description": "Other .void files imported to inherit blocks from.",
      "items": {
        "type": "string",
        "description": "Relative path to an imported .void file."
      }
    }
  },
  "$defs": {
    "Block": {
      "type": "object",
      "description": "A reusable API component block — endpoint, auth, headers, params, body, or request.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this block (auto-generated)."
        },
        "type": {
          "type": "string",
          "enum": ["endpoint", "auth", "headers", "params", "body", "request", "assertion"],
          "description": "The type of block."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for the block."
        },
        "description": {
          "type": "string",
          "description": "Markdown documentation for the block."
        },
        "method": {
          "type": "string",
          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
          "description": "HTTP method (for request blocks)."
        },
        "url": {
          "type": "string",
          "description": "URL or URL template for the request."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "HTTP headers as key-value pairs."
        },
        "params": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Query parameters as key-value pairs."
        },
        "body": {
          "type": "object",
          "description": "Request body definition.",
          "properties": {
            "contentType": {
              "type": "string",
              "description": "Content-Type header value."
            },
            "data": {
              "description": "The request body content."
            }
          }
        },
        "auth": {
          "$ref": "#/$defs/AuthBlock"
        },
        "assertions": {
          "type": "array",
          "description": "Response assertions for testing.",
          "items": {
            "$ref": "#/$defs/Assertion"
          }
        },
        "scripts": {
          "$ref": "#/$defs/Scripts"
        },
        "extends": {
          "type": "string",
          "description": "Block ID this block inherits from."
        }
      }
    },
    "AuthBlock": {
      "type": "object",
      "description": "Authentication configuration block.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["bearer", "basic", "apikey", "oauth2", "none"],
          "description": "Authentication scheme."
        },
        "token": {
          "type": "string",
          "description": "Token value or template variable."
        },
        "username": {
          "type": "string"
        },
        "password": {
          "type": "string"
        },
        "key": {
          "type": "string",
          "description": "API key value or template variable."
        },
        "placement": {
          "type": "string",
          "enum": ["header", "query"],
          "description": "Where to place the API key."
        }
      }
    },
    "Assertion": {
      "type": "object",
      "description": "A test assertion on the response.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["status", "body", "header", "json-path"],
          "description": "What to assert on."
        },
        "expected": {
          "description": "Expected value."
        },
        "path": {
          "type": "string",
          "description": "JSON path for json-path assertions."
        }
      }
    },
    "Scripts": {
      "type": "object",
      "description": "Pre/post-request scripts.",
      "properties": {
        "pre": {
          "type": "string",
          "description": "Script to run before the request (JavaScript, Python, or shell)."
        },
        "post": {
          "type": "string",
          "description": "Script to run after the request."
        },
        "language": {
          "type": "string",
          "enum": ["javascript", "python", "shell"],
          "description": "Script language."
        }
      }
    }
  }
}