Skip to main content

Policy Spec Schema

This page defines the complete JSON Schema for Policy specifications in Fascia. A Policy is a rule enforced at design time (not runtime) to prevent unsafe operations. Policies are evaluated by the Risk Engine before a Tool can be deployed.

JSON Schema​

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "version", "description", "type", "condition", "action"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-zA-Z0-9]*$",
      "description": "camelCase policy name (e.g., maxRowLimit, budgetCheck)"
    },
    "version": {
      "type": "integer",
      "minimum": 1
    },
    "description": {
      "type": "string"
    },
    "type": {
      "enum": ["rowLimit", "budgetCheck", "rateLimit", "custom"],
      "description": "Policy category"
    },
    "condition": {
      "type": "string",
      "description": "Value DSL boolean expression. Policy triggers when this is TRUE."
    },
    "action": {
      "enum": ["block", "warn", "escalate"],
      "description": "What happens when the condition is met"
    },
    "message": {
      "type": "string",
      "description": "Human-readable message shown when policy triggers"
    },
    "parameters": {
      "type": "object",
      "description": "Type-specific parameters",
      "properties": {
        "maxRows": { "type": "integer", "description": "For rowLimit type" },
        "maxAmount": { "type": "number", "description": "For budgetCheck type" },
        "maxRequestsPerMinute": { "type": "integer", "description": "For rateLimit type" }
      }
    }
  }
}

Top-Level Properties​

PropertyTypeRequiredDescription
namestringYescamelCase policy name (e.g., maxRowLimit, budgetCheck). Must match ^[a-z][a-zA-Z0-9]*$.
versionintegerYesImmutable version number, starting at 1.
descriptionstringYesHuman-readable description of the policy's purpose.
typeenumYesPolicy category: rowLimit, budgetCheck, rateLimit, or custom.
conditionstringYesA Value DSL boolean expression. The policy triggers when this evaluates to true.
actionenumYesThe response when the condition is met: block, warn, or escalate.
messagestringNoHuman-readable message displayed to the user when the policy triggers.
parametersobjectNoType-specific parameters that provide concrete thresholds.

Actions​

ActionBehavior
blockThe operation is prevented from proceeding. The tool cannot be deployed or executed until the condition is resolved.
warnThe user is shown a warning with the message text. The operation can proceed if the user explicitly acknowledges the warning. The acknowledgment is recorded in the audit log.
escalateThe issue is flagged for manual review by an administrator. The operation is paused until approval is granted.

Policy Types​

rowLimit​

Limits the number of rows a single operation can affect. Prevents accidental mass updates or deletes.

Parameters:

ParameterTypeDescription
maxRowsintegerMaximum number of rows a single operation may affect.

Example:

{
  "name": "maxRowLimit",
  "version": 1,
  "description": "Prevent operations affecting more than 100 rows",
  "type": "rowLimit",
  "condition": "affectedRowCount > 100",
  "action": "block",
  "message": "This operation would affect more than 100 rows. Please add a filter.",
  "parameters": {
    "maxRows": 100
  }
}

This policy blocks any write operation that would modify more than 100 rows in a single execution. The tool designer must add a WHERE filter or batch the operation to proceed.

budgetCheck​

Enforces spending limits on external service calls. Useful for controlling costs on payment processing, email sending, or third-party API usage.

Parameters:

ParameterTypeDescription
maxAmountnumberMaximum monetary amount allowed within the budget period.

Example:

{
  "name": "monthlyBudgetCheck",
  "version": 1,
  "description": "Warn when monthly spend exceeds budget",
  "type": "budgetCheck",
  "condition": "workspace.monthlySpend > workspace.budgetLimit",
  "action": "warn",
  "message": "Monthly budget exceeded. Current spend: {workspace.monthlySpend}",
  "parameters": {
    "maxAmount": 1000
  }
}

This policy issues a warning when the workspace's cumulative monthly spending exceeds the configured budget limit. The workspace owner must acknowledge the warning before the operation proceeds.

rateLimit​

Limits request frequency per user, per email, or per IP address. Commonly used to protect authentication endpoints against brute-force attacks.

Parameters:

ParameterTypeDescription
maxRequestsPerMinuteintegerMaximum number of requests allowed within a one-minute window.

Example:

{
  "name": "loginRateLimit",
  "version": 1,
  "description": "Rate limit login attempts",
  "type": "rateLimit",
  "condition": "requestCount(user.email, '1m') > 5",
  "action": "block",
  "message": "Too many login attempts. Please wait and try again.",
  "parameters": {
    "maxRequestsPerMinute": 5
  }
}

This policy blocks login attempts when a given email address exceeds 5 requests within a one-minute window. The user must wait for the window to expire before retrying.

custom​

For policies that do not fit into the predefined categories. Custom policies use arbitrary Value DSL conditions and can enforce any business rule.

Example:

{
  "name": "requireConfirmationForHighValue",
  "version": 1,
  "description": "Escalate operations involving amounts over $10,000",
  "type": "custom",
  "condition": "input.amount > 10000",
  "action": "escalate",
  "message": "Operations over $10,000 require administrator approval."
}

Referencing Policies from Tools​

Policies are referenced by name in the policies array of a Tool spec. When a tool is invoked, all referenced policies are evaluated at step 3 of the Execution Contract, before the transaction begins.

{
  "name": "createReservation",
  "policies": ["maxRowLimit", "monthlyBudgetCheck"],
  "...": "..."
}

If any policy with action: "block" triggers, execution stops immediately and an error is returned. Policies with action: "warn" require acknowledgment before proceeding.

Design-Time vs Runtime​

Policies in Fascia operate primarily at design time. The Risk Engine evaluates policies during spec validation and deployment:

  • Design-time enforcement: When a tool spec is created or updated, the Risk Engine checks whether the flow patterns comply with all referenced policies. A tool that structurally violates a block policy cannot be deployed.
  • Runtime evaluation: Some policies (e.g., rateLimit, budgetCheck) involve dynamic data that can only be evaluated at execution time. These are checked at step 3 of the Execution Contract.

The distinction ensures that structurally unsafe tools are caught before they ever run, while dynamic thresholds are enforced at the point of invocation.

See Also​