Harbor predicate DSL

Harbor uses predicate_dsl to define the release rule attached to an intent. When evidence is later submitted, Harbor evaluates that evidence against the stored rule and returns a pass or fail result with an audit trace.

This format is intentionally narrow. It supports deterministic checks on the submitted evidence and on the intent budget, but it does not run arbitrary code, call external services, or read data from another tenant.

Use predicate_dsl when you want to send the rule inline on POST /intents. Use predicate_ref when you want a reusable, versioned tenant policy managed centrally. For the surrounding endpoints, see the Harbor API reference.

Where this appears

Harbor rejects malformed or oversized predicate documents at intent creation with 400 Bad Request. During evidence submission, business-rule mismatches usually return passed: false, while evidence-shape problems can return 422 Unprocessable Entity.

Product guarantees

• Deterministic evaluation: the same predicate and evidence produce the same result.
• Bounded execution: Harbor enforces fixed depth, path, and fuel limits so evaluation remains predictable.
• Tenant-scoped inputs only: evaluation uses only the current intent, its declared evidence schema, and the submitted evidence payload.
• Stable release rule: Harbor binds the predicate to the intent at creation time so the rule evaluated later is the same rule the parties approved.

For the broader isolation model, see Tenant model.

Document envelope

Every predicate document must include:

{
  "version": 1,
  "root": { "op": "true" }
}
{
  "version": 1,
  "root": { "op": "true" }
}

Treat unknown version values as unsupported.

Evidence paths

Paths are arrays of string keys into the submitted evidence JSON object. They support nested objects only.

Example:

{ "path": ["status"] }
{ "path": ["status"] }

reads payload.status, while:

{ "path": ["job", "result", "status"] }
{ "path": ["job", "result", "status"] }

reads payload.job.result.status.

Clauses (op)

All clauses are JSON objects with an op field in snake_case.

Boolean composition

Evidence checks

Schema-aware check

This is useful when you want to require a field without hard-coding one exact value. evidence_schema follows a minimal JSON Schema-style contract, for example:

{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "cost": { "type": "integer" }
  }
}
{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "cost": { "type": "integer" }
  }
}

Supported type values are null, boolean, string, integer, number, array, and object. An array of type strings is also allowed for multi-type fields.

Limits

These limits apply at both intent creation and evidence evaluation.

Evaluation result (predicate_evaluation)

On successful evidence submission, Harbor includes a predicate_evaluation object shaped like:

{
  "passed": true,
  "trace": [
    {
      "kind": "completion",
      "detail": "value matched",
      "data": { "path": "status", "passed": true, "expected": "completed", "observed": "completed" }
    }
  ]
}
{
  "passed": true,
  "trace": [
    {
      "kind": "completion",
      "detail": "value matched",
      "data": { "path": "status", "passed": true, "expected": "completed", "observed": "completed" }
    }
  ]
}

Logical failures such as an eq mismatch return passed: false with a trace explaining what failed. That is different from a malformed request or invalid evidence shape.

Direct DSL vs managed policies

• Use predicate_dsl when each intent carries its own inline rule.
• Use predicate_ref when you want a reusable tenant policy with versioning, preview, and controlled rollout.
• Managed policy lifecycle endpoints are part of the Harbor API reference.

Examples

Accept any evidence (useful for smoke tests):

{
  "version": 1,
  "root": { "op": "true" }
}
{
  "version": 1,
  "root": { "op": "true" }
}

Require a completed status and keep cost within budget:

{
  "version": 1,
  "root": {
    "op": "and",
    "clauses": [
      { "op": "completion", "path": ["status"], "value": "completed" },
      { "op": "budget_cap", "path": ["cost"] }
    ]
  }
}
{
  "version": 1,
  "root": {
    "op": "and",
    "clauses": [
      { "op": "completion", "path": ["status"], "value": "completed" },
      { "op": "budget_cap", "path": ["cost"] }
    ]
  }
}

Evidence might be { "status": "completed", "cost": 5000 } with amount_cents >= 5000.

Require a declared field from the evidence schema:

{
  "version": 1,
  "root": { "op": "schema_field", "field": "invoice_id" }
}
{
  "version": 1,
  "root": { "op": "schema_field", "field": "invoice_id" }
}

Evidence must include top-level invoice_id, and evidence_schema.properties.invoice_id.type must describe its JSON type.

Managed policy templates

Harbor ships managed templates that materialize tenant parameters into validated predicate_dsl. Templates are listed at GET /harbor/policy/v1/templates and previewed or tested via the policy registry API and console workbench.

Preset IDs, sample evidence, and parameter defaults live in the shared completion preset catalog (catalog.json).

api_response_v1 parameters:

{
  "http_status_path": ["http_status"],
  "expected_http_status": 200
}
{
  "http_status_path": ["http_status"],
  "expected_http_status": 200
}

webhook_confirmation_v1 parameters:

{
  "event_type_path": ["event_type"],
  "expected_event_type": "payment.succeeded"
}
{
  "event_type_path": ["event_type"],
  "expected_event_type": "payment.succeeded"
}

artifact_hash_v1 parameters:

{
  "operation_path": ["operation"],
  "expected_operation": "attested"
}
{
  "operation_path": ["operation"],
  "expected_operation": "attested"
}

Integrators collect vendor signals out of band and place references and digests in evidence; the predicate VM evaluates only the submitted JSON.

Version support

Related

• Harbor API reference
• Completion preset catalog
• Intent lifecycle
• Tenant model
• Errors