TealfabricLibrary

Process Metadata Schema Definition

Document information
  • Canonical URL: /docs/02_automations-and-processflow/32_process-metadata-schema
  • Version: 2026-05-08
  • Tags: processflow, schema, reference

This guide defines the metadata schema used to describe ProcessFlow processes in a consistent, machine-readable format. Strong metadata makes process discovery, validation, and orchestration safer because tools and teams can rely on stable contracts for inputs, outputs, and guardrails. Use this schema when publishing new processes or updating existing ones so operational behavior remains predictable.

Process metadata schema lifecycle showing standardized process descriptors, validation rules, and reliable orchestration across process discovery, execution, and governance.

Use a consistent metadata URI and resource shape

Metadata resources follow the URI pattern process://tealfabric/{process_name}/metadata. Each resource should include identity fields, business context, and explicit input/output schema contracts. A process can still run without rich metadata, but high-quality metadata dramatically improves integration quality and supportability.

At minimum, include process_id, version, name, description, category, input_schema, and output_schema. Optional sections such as tags, dependencies, error_handling, and guardrails are strongly recommended for production use, especially when multiple teams consume the same process.

Validate metadata before publishing

Before publishing metadata, validate JSON structure and naming conventions, then ensure the payload references a real process ID and current behavior. Running validation in CI is safer than relying on manual review because schema errors are easy to miss and can break downstream orchestration.

From ProcessFlow or WebApp step code, validate metadata through the injected api service. External CI jobs should use the curl example below.

async function validateMetadata(metadata: Record<string, unknown>) {
  const result = await api.post("/api/v1/process-metadata?action=validate", metadata);
  if (!result.success) {
    throw new Error("Validation request failed");
  }
  return result;
}
curl -X POST "https://<YOUR_DOMAIN>/api/v1/process-metadata?action=validate" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "proc_entity_linking",
    "version": "1.0",
    "name": "Entity Linking",
    "description": "Links entities to a platform using matching criteria",
    "category": "entity_management",
    "input_schema": {
      "type": "object",
      "properties": {
        "platform_id": { "type": "string" }
      },
      "required": ["platform_id"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "status": { "type": "string" }
      }
    }
  }'

{
  "success": true,
  "data": {
    "valid": true,
    "warnings": [],
    "normalized_process_id": "proc_entity_linking"
  }
}

Recommended schema contract

Use Draft 7-compatible JSON Schema for both input_schema and output_schema. Process IDs should follow a stable format such as proc_<name> using lowercase letters, numbers, and underscores. Categories should be selected from a shared list so search, filtering, and reporting stay consistent across teams.

For reliability, include output fields that let callers branch safely, such as status, message, and optional error context. This avoids brittle client assumptions and keeps process-to-process chaining predictable.

Production guidance for metadata quality

Add realistic examples in examples and keep them in sync with current process behavior after every release. Document rate limits, allowed roles, and error handling strategy in guardrails and error_handling so operators can understand execution risk before rollout. Use last_updated and maintainer ownership fields to make stale metadata easy to detect.

When metadata is treated as part of your release artifact, integrations break less often and incident triage becomes faster. Consistent schemas are one of the highest-leverage improvements for process platform maturity.

Related documentation