System Functions

Reserved namespaces and built-in functions

Overview

Function names beginning with vend. are reserved for system functions. Applications MUST NOT define functions in this namespace.

System functions provide protocol-level capabilities like health checks, introspection, and operation management.

Reserved Namespace

Rules

Function names starting with vend. are reserved
Applications MUST NOT define custom functions with this prefix
Servers SHOULD implement core system functions
Clients MAY call system functions like any other function

Format

vend.<category>.<action>

Categories:

vend.ping — Simple connectivity check
vend.health — Comprehensive health check
vend.describe — Introspection
vend.capabilities — Feature discovery
vend.operation.* — Async operation management
vend.replay.* — Replay queue management

Core System Functions

vend.ping

Health check function. MUST return immediately if service is healthy.

Request:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_health",
  "call": {
    "function": "vend.ping",
    "version": "1",
    "arguments": {}
  }
}

Response:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_health",
  "result": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "extensions": [
    {
      "urn": "urn:vnd:ext:tracing",
      "data": {
        "trace_id": "tr_abc123",
        "span_id": "span_server_001",
        "duration": { "value": 1, "unit": "millisecond" }
      }
    }
  ],
  "meta": {
    "node": "orders-api-2"
  }
}

Arguments: None required

Returns:

Field	Type	Description
`status`	string	Health status: MUST be one of `healthy`, `degraded`, `unhealthy`
`timestamp`	string	MUST be ISO 8601 timestamp
`details`	object	OPTIONAL additional health info

vend.health

Comprehensive health check with component-level status. Use for load balancer health checks, dependency monitoring, and operational visibility.

Request:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_health",
  "call": {
    "function": "vend.health",
    "version": "1",
    "arguments": {}
  }
}

Response:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_health",
  "result": {
    "status": "healthy",
    "components": {
      "database": {
        "status": "healthy",
        "latency": { "value": 2, "unit": "millisecond" }
      },
      "cache": {
        "status": "healthy",
        "latency": { "value": 1, "unit": "millisecond" }
      },
      "queue": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Arguments:

Field	Type	Required	Description
`component`	string	No	Check specific component only
`include_details`	boolean	No	Include detailed check info (default: `true`)

Returns:

Field	Type	Description
`status`	string	Aggregate status (see below)
`components`	object	Component health status
`functions`	object	Function-level health (optional)
`timestamp`	string	ISO 8601 timestamp
`version`	string	Optional service version

Health Status Values

Status	Description	HTTP Equivalent
`healthy`	All systems operational	200
`degraded`	Functional but impaired	200
`unhealthy`	Not able to serve requests	503

Component Check Object

Each component in components contains:

Field	Type	Description
`status`	string	Component status
`latency`	object	Optional response time
`message`	string	Optional status message
`last_check`	string	Optional last successful check time

Aggregate Status Rules

The top-level status MUST reflect the worst component status:

If ANY component is unhealthy → aggregate is unhealthy
If ANY component is degraded (and none unhealthy) → aggregate is degraded
If ALL components are healthy → aggregate is healthy

Check Specific Component

// Request
{
  "call": {
    "function": "vend.health",
    "version": "1",
    "arguments": {
      "component": "database"
    }
  }
}

// Response
{
  "result": {
    "status": "healthy",
    "components": {
      "database": {
        "status": "healthy",
        "latency": { "value": 2, "unit": "millisecond" },
        "message": "Primary connection active"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Degraded Example

{
  "result": {
    "status": "degraded",
    "components": {
      "database": {
        "status": "healthy",
        "latency": { "value": 3, "unit": "millisecond" }
      },
      "cache": {
        "status": "degraded",
        "message": "Failover to secondary, elevated latency",
        "latency": { "value": 45, "unit": "millisecond" }
      },
      "external_api": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Unhealthy Example

{
  "result": {
    "status": "unhealthy",
    "components": {
      "database": {
        "status": "unhealthy",
        "message": "Connection refused",
        "last_check": "2024-01-15T10:29:55Z"
      },
      "cache": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Liveness vs Readiness

For Kubernetes-style probes, use the component argument:

Probe	Component	Purpose
Liveness	`"self"`	Is the process alive?
Readiness	(omit)	Can it serve traffic?

// Liveness probe - just checks if service is running
{
  "arguments": {
    "component": "self",
    "include_details": false
  }
}

// Response
{
  "result": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Standard Component Names

Services SHOULD use these component names when applicable:

Component	Description
`self`	The service process itself
`database`	Primary database
`cache`	Caching layer (Redis, Memcached)
`queue`	Message queue
`storage`	Object/file storage
`search`	Search engine (Elasticsearch)
`<service>_api`	External service dependency

Function-Level Health

Functions can report their own health status independently of component health. This enables graceful degradation where some functions remain available while others are temporarily disabled.

Function Health Object

Field	Type	Description
`status`	string	Function status (see below)
`message`	string	Optional explanation
`until`	string	Optional ISO 8601 timestamp
`retry_after`	object	Optional duration before retry

Function Status Values

Status	Description
`healthy`	Function is fully operational
`degraded`	Function works but with limitations
`disabled`	Function turned off (feature flag, deprecated, etc.)
`maintenance`	Function under scheduled maintenance

Example: Function Disabled

{
  "result": {
    "status": "degraded",
    "components": {
      "database": { "status": "healthy" },
      "cache": { "status": "healthy" }
    },
    "functions": {
      "reports.generate": {
        "status": "disabled",
        "message": "Disabled during maintenance window",
        "until": "2024-01-15T12:00:00Z"
      },
      "orders.create": {
        "status": "healthy"
      },
      "orders.list": {
        "status": "healthy"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Example: Function Degraded

{
  "result": {
    "status": "degraded",
    "components": {
      "database": { "status": "healthy" },
      "external_api": { "status": "degraded" }
    },
    "functions": {
      "orders.create": {
        "status": "degraded",
        "message": "Payment validation disabled, orders require manual review"
      },
      "exports.create": {
        "status": "degraded",
        "message": "Rate limited due to high load",
        "retry_after": { "value": 30, "unit": "second" }
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Aggregate Status with Functions

Function health contributes to aggregate status:

If ANY function is disabled → aggregate is at least degraded
Function degraded → aggregate is at least degraded
Component unhealthy always takes precedence → aggregate is unhealthy

Calling Disabled Functions

When a function is marked disabled, calls to that function SHOULD return:

{
  "errors": [{
    "code": "FUNCTION_DISABLED",
    "message": "Function temporarily disabled",
    "retryable": false,
    "details": {
      "function": "reports.generate",
      "reason": "Feature flag disabled"
    }
  }]
}

Calling Functions Under Maintenance

When a function is marked maintenance, calls MUST return HTTP 503:

{
  "errors": [{
    "code": "FUNCTION_MAINTENANCE",
    "message": "Function under scheduled maintenance",
    "retryable": true,
    "details": {
      "function": "reports.generate",
      "reason": "Report engine upgrade",
      "until": "2024-01-15T12:00:00Z",
      "retry_after": { "value": 30, "unit": "minute" }
    }
  }]
}

vend.capabilities

Discover what the service supports.

Request:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_caps",
  "call": {
    "function": "vend.capabilities",
    "version": "1",
    "arguments": {}
  }
}

Response:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_caps",
  "result": {
    "service": "orders-api",
    "protocol_versions": ["0.1.0"],
    "extensions": [
      {
        "urn": "urn:vnd:ext:async",
        "documentation": "urn:vnd:ext:async"
      }
    ],
    "functions": [
      "orders.create",
      "orders.get",
      "orders.list",
      "orders.cancel"
    ],
    "limits": {
      "max_request_bytes": 1048576,
      "default_deadline": { "value": 30, "unit": "second" }
    }
  }
}

Arguments: None required

Returns:

Field	Type	Description
`service`	string	Service identifier
`protocol_versions`	array	Supported Vend protocol versions
`extensions`	array	Server-wide supported extensions (see note)
`functions`	array	Available function names (without versions)
`limits`	object	Service limits

Note: Extensions listed in vend.capabilities represent server-wide defaults. Individual functions MAY restrict which extensions they accept. Use vend.describe to discover per-function extension support.

vend.describe

Get detailed information about a specific function, including schema, side effects, and capabilities.

Request:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_describe",
  "call": {
    "function": "vend.describe",
    "version": "1",
    "arguments": {
      "function": "orders.create"
    }
  }
}

Response:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_describe",
  "result": {
    "function": "orders.create",
    "description": "Create a new order",
    "side_effects": ["create"],
    "versions": [
      {
        "version": "1",
        "status": "stable",
        "description": "Original version",
        "deprecated": {
          "reason": "Use version 2 for improved validation",
          "sunset": "2025-06-01"
        }
      },
      {
        "version": "2",
        "status": "stable",
        "description": "Current version with improved validation",
        "schema": {
          "arguments": {
            "type": "object",
            "properties": {
              "customer_id": { "type": "string" },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "product_id": { "type": "string" },
                    "quantity": { "type": "integer", "minimum": 1 }
                  },
                  "required": ["product_id", "quantity"]
                }
              },
              "shipping_address": { "$ref": "#/definitions/address" }
            },
            "required": ["customer_id", "items"]
          },
          "returns": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "status": { "type": "string", "enum": ["pending", "confirmed"] },
              "total": { "type": "number" }
            }
          },
          "definitions": {
            "address": {
              "type": "object",
              "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }
              }
            }
          }
        }
      },
      {
        "version": "3",
        "status": "beta",
        "description": "Beta with async support"
      }
    ],
    "recommended_version": "2"
  }
}

Arguments:

Field	Type	Required	Description
`function`	string	Yes	Function name to describe
`version`	string	No	Specific version (returns all if omitted)
`include_schema`	boolean	No	Include JSON Schema (default: `true`)

Returns:

Field	Type	Description
`function`	string	Function name
`description`	string	Human-readable description
`side_effects`	array	Side effects (see below). Empty array means read-only.
`versions`	array	Available versions with status
`recommended_version`	string	Suggested version to use

Side Effects

The side_effects array indicates what state changes a function may cause:

Value	Description
`create`	Creates new resources
`update`	Modifies existing resources
`delete`	Removes resources

An empty array ([]) indicates a read-only function with no side effects.

Schema Object

Each version MAY include a schema object with JSON Schema definitions:

Field	Type	Description
`arguments`	object	JSON Schema for function arguments
`returns`	object	JSON Schema for successful result
`definitions`	object	Shared schema definitions

Schemas use JSON Schema Draft 2020-12 with these extensions:

$ref for referencing definitions
Standard formats: date-time, email, uri, etc.

Version Status Values

Status	Description
`stable`	Production-ready, fully supported
`beta`	Testing, MAY change
`removed`	No longer available (MAY be omitted from list)

Deprecation is indicated by the presence of a deprecated object, not a status value. See Deprecated Object.

Pagination Discovery

For list functions, vend.describe returns pagination capabilities:

{
  "result": {
    "function": "orders.list",
    "description": "List orders with filtering and pagination",
    "side_effects": [],
    "versions": [
      {
        "version": "1",
        "status": "stable",
        "pagination": {
          "styles": ["cursor", "offset"],
          "default_style": "cursor",
          "default_limit": 50,
          "max_limit": 100
        }
      }
    ],
    "recommended_version": "1"
  }
}

Pagination Object

Field	Type	Description
`styles`	array	Supported pagination styles
`default_style`	string	Style used when not specified
`default_limit`	integer	Items per page when not specified
`max_limit`	integer	Maximum allowed limit

Pagination Styles

Style	Description
`cursor`	Opaque cursor-based pagination
`offset`	Numeric offset pagination
`keyset`	Key-based pagination (e.g., `after_id`)

Query Capabilities

For functions supporting filtering, sorting, and sparse fieldsets:

{
  "result": {
    "function": "orders.list",
    "side_effects": [],
    "versions": [
      {
        "version": "1",
        "status": "stable",
        "capabilities": {
          "filters": {
            "self": ["id", "status", "created_at", "total_amount"],
            "customer": ["id", "type", "country_code"]
          },
          "sorts": ["created_at", "total_amount", "status"],
          "fields": {
            "self": ["id", "status", "total_amount", "created_at", "updated_at"],
            "customer": ["id", "name", "email"]
          },
          "relationships": ["customer", "items", "shipments"]
        },
        "pagination": {
          "styles": ["cursor"],
          "default_limit": 50,
          "max_limit": 100
        }
      }
    ]
  }
}

Capabilities Object

Field	Type	Description
`filters`	object	Filterable attributes by resource
`sorts`	array	Sortable attributes
`fields`	object	Selectable fields by resource
`relationships`	array	Includable relationships

Extension Support

Functions can declare which extensions they support, overriding server-wide defaults:

{
  "result": {
    "function": "orders.create",
    "description": "Create a new order",
    "side_effects": ["create"],
    "versions": [
      {
        "version": "2",
        "status": "stable",
        "extensions": {
          "supported": ["urn:vnd:ext:idempotency", "urn:vnd:ext:dry-run", "urn:vnd:ext:tracing"]
        }
      }
    ]
  }
}

Extensions Object

Field	Type	Description
`supported`	array	Extensions this function accepts (allowlist)
`excluded`	array	Extensions this function rejects (blocklist)

Rules

If extensions is omitted → function supports all server-wide extensions
If supported is present → only listed extensions are accepted
If excluded is present → server-wide extensions minus these are accepted
MUST NOT specify both supported and excluded

Example: Excluding Extensions

{
  "result": {
    "function": "orders.list",
    "description": "List orders",
    "side_effects": [],
    "versions": [
      {
        "version": "1",
        "status": "stable",
        "extensions": {
          "excluded": ["urn:vnd:ext:idempotency", "urn:vnd:ext:dry-run"]
        }
      }
    ]
  }
}

Unsupported Extension Error

When a client requests an extension that a function doesn’t support:

{
  "errors": [{
    "code": "EXTENSION_NOT_APPLICABLE",
    "message": "Caching extension not applicable to write operations",
    "retryable": false,
    "source": { "pointer": "/extensions/0" },
    "details": {
      "extension": "urn:vnd:ext:caching",
      "function": "orders.create"
    }
  }]
}

See Errors for the full error specification.

vend.operation.status

Check status of an async operation. See Async.

Request:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_op_status",
  "call": {
    "function": "vend.operation.status",
    "version": "1",
    "arguments": {
      "operation_id": "op_xyz789"
    }
  }
}

Arguments:

Field	Type	Required	Description
`operation_id`	string	Yes	Operation ID to check

Returns: See Async for response format.

vend.operation.cancel

Cancel a pending async operation.

Request:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_op_cancel",
  "call": {
    "function": "vend.operation.cancel",
    "version": "1",
    "arguments": {
      "operation_id": "op_xyz789"
    }
  }
}

Arguments:

Field	Type	Required	Description
`operation_id`	string	Yes	Operation ID to cancel

Returns:

Field	Type	Description
`operation_id`	string	Operation ID
`status`	string	New status (MUST be `cancelled`)
`cancelled_at`	string	MUST be ISO 8601 timestamp

vend.operation.list

List operations for the current caller.

Request:

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "req_op_list",
  "call": {
    "function": "vend.operation.list",
    "version": "1",
    "arguments": {
      "status": "processing",
      "limit": 10
    }
  }
}

Arguments:

Field	Type	Required	Description
`status`	string	No	Filter by status
`function`	string	No	Filter by function name
`limit`	integer	No	Max results (default 50)
`cursor`	string	No	Pagination cursor

Returns:

{
  "operations": [
    {
      "id": "op_abc123",
      "function": "reports.generate",
      "version": "1",
      "status": "processing",
      "progress": 0.45,
      "started_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "op_def456",
      "function": "exports.create",
      "version": "1",
      "status": "processing",
      "progress": 0.12,
      "started_at": "2024-01-15T10:31:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6Im9wX2RlZjQ1NiJ9"
}

Future Reserved Namespaces

These namespaces are reserved for potential future use:

Namespace	Intended Purpose
`vend.auth.*`	Authentication functions
`vend.schema.*`	Schema introspection
`vend.metrics.*`	Metrics and observability
`vend.config.*`	Configuration discovery

Implementation Requirements

Required Functions

Servers SHOULD implement:

vend.ping — Simple connectivity check
vend.health — Comprehensive health check

Recommended Functions

Servers SHOULD implement if applicable:

vend.capabilities — For service discovery
vend.describe — For API exploration
vend.operation.* — If supporting async operations

Ping vs Health

Function	Purpose	Use Case
`vend.ping`	Fast connectivity check	Heartbeats, basic liveness
`vend.health`	Dependency-aware health	Load balancers, readiness probes

Use vend.ping when you just need to know if the service is reachable. Use vend.health when you need to know if the service can actually serve requests (dependencies are healthy).

Custom System Functions

Organizations MAY define additional system functions within their own namespace:

myorg.system.audit
myorg.system.config

These MUST NOT use the vend. prefix.

Examples

Health Check

// Request
{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "health_001",
  "call": {
    "function": "vend.ping",
    "version": "1"
  }
}

// Response
{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "health_001",
  "result": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z",
    "details": {
      "database": "connected",
      "cache": "connected",
      "queue": "connected"
    }
  }
}

Function Discovery

// Request
{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "discover_001",
  "call": {
    "function": "vend.capabilities",
    "version": "1"
  }
}

// Response
{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "discover_001",
  "result": {
    "service": "user-service",
    "protocol_versions": ["0.1.0"],
    "extensions": [
      { "urn": "urn:vnd:ext:async" }
    ],
    "functions": [
      "users.create",
      "users.get",
      "users.update",
      "users.delete",
      "users.list"
    ],
    "limits": {
      "default_deadline": { "value": 10, "unit": "second" }
    }
  }
}

Degraded Health

{
  "protocol": { "name": "vend", "version": "0.1.0" },
  "id": "health_002",
  "result": {
    "status": "degraded",
    "timestamp": "2024-01-15T10:30:00Z",
    "details": {
      "database": "connected",
      "cache": "disconnected",
      "queue": "connected"
    },
    "message": "Cache unavailable, operating with degraded performance"
  }
}