CEL Work Scopes

Hypercert work scopes describe what work was done. A CEL expression alongside the human-readable work scope makes hypercerts machine-verifiable, composable, and queryable.

CEL (Common Expression Language) is an open-source expression language built by Google for evaluating conditions in distributed systems. It's used by Kubernetes, Firebase, and Google Cloud IAM.

Why structured scopes matter

A community in coastal Kenya mints a hypercert for "mangrove restoration and environmental education." A collective in Uganda creates one for "agroforestry with beekeeping." A drone operator in the Amazon documents "biodiversity monitoring in the Negro River region." These are all legible to a person reading them one at a time. They're invisible to any system trying to connect funders to relevant work at scale.

As the Hypercerts Protocol grows on ATProto — with actions, evaluations, and evidence living as persistent, portable records — the richer the network becomes, the harder it is to find, compare, validate, and compose claims when the most important field is unstructured text.

Architecture: two layers

The design uses two complementary layers:

1. Vocabulary layer — workScopeTag records define what each tag means (e.g., what mangrove_restoration refers to, its description, hierarchy, and links to external ontologies).
2. Composition layer — celExpression objects compose those tags into evaluable logic on activity records (e.g., "this work includes mangrove restoration AND environmental education, AND is in Kenya").

workScopeTag records (vocabulary)
  ├── mangrove_restoration
  ├── environmental_education
  ├── fishpond_management
  └── ecotourism


           ↓ referenced by


celExpression (composition)
  expression: scope.hasAll(['mangrove_restoration', 'environmental_education'])
                && scope.hasAny(['fishpond_management', 'ecotourism'])
                && location.country == 'KE'
  usedTags: [strongRef → mangrove_restoration, strongRef → environmental_education, ...]


           ↓ embedded in


activity.workScope (union)
  → celExpression   (structured, machine-evaluable)
  → workScopeString (simple free-form fallback)

The vocabulary layer tells you what a tag means. The composition layer tells you what logic applies to a specific hypercert. The workScopeString fallback supports simple free-form scopes.

Lexicon schemas

org.hypercerts.ontology.celExpression

A CEL expression object embedded inline in the activity.workScope union. It's intentionally an object type (not a record) so it can be embedded directly without requiring a separate collection.

org.hypercerts.ontology.workScopeTag

A reusable scope atom — the building block of the vocabulary. Each record represents a single concept like mangrove_restoration or biodiversity_monitoring.

activity.workScope union

The workScope field on org.hypercerts.claim.activity accepts two variants:

• celExpression — a structured, machine-evaluable scope (described above).
• workScopeString — a simple free-form string for cases where a CEL expression isn't needed.

Examples

Mangrove restoration in coastal Kenya

{
  "$type": "org.hypercerts.claim.activity",
  "title": "Tsunza Mangrove Restoration & Education",
  "workScope": {
    "$type": "org.hypercerts.ontology.celExpression",
    "expression": "scope.hasAll(['mangrove_restoration', 'environmental_education']) && scope.hasAny(['fishpond_management', 'ecotourism']) && location.country == 'KE'",
    "usedTags": [
      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/mangrove_restoration", "cid": "..." },
      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/environmental_education", "cid": "..." },
      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/fishpond_management", "cid": "..." },
      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/ecotourism", "cid": "..." }
    ],
    "version": "v1",
    "createdAt": "2025-07-22T10:00:00Z"
  },
  "startDate": "2024-06-01T00:00:00Z",
  "endDate": "2025-12-31T23:59:59Z"
}

Agroforestry in Uganda

{
  "workScope": {
    "$type": "org.hypercerts.ontology.celExpression",
    "expression": "scope.hasAll(['agroforestry', 'tree_planting', 'beekeeping']) && location.country == 'UG'",
    "usedTags": [
      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/agroforestry", "cid": "..." },
      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/tree_planting", "cid": "..." },
      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/beekeeping", "cid": "..." }
    ],
    "version": "v1",
    "createdAt": "2025-06-15T08:00:00Z"
  }
}

What CEL unlocks

Funder matching

Funders can define their criteria as CEL expressions and the appview matches them against existing hypercerts:

// "All mangrove work in East Africa"
scope.has("mangrove_restoration") && location.country in ["KE", "TZ", "MZ", "MG"]

Evaluation matching

An auditor who verified mangrove survival rates can express applicability as a CEL condition, and the appview automatically matches it to relevant hypercerts:

scope.has("mangrove_restoration")
  && location.country == "KE"
  && time.end >= timestamp("2025-01-01T00:00:00Z")

Overlap detection

When someone mints a new hypercert, CEL can check whether the claimed work scope overlaps with existing claims:

existing.scope.overlaps(new.scope)
  && existing.time.start < new.time.end
  && new.time.start < existing.time.end
  && existing.location.region == new.location.region

Measurement-based queries

Because CEL can access linked measurement records, funders can write queries that go beyond tags:

// "Agroforestry that planted 500+ verified trees"
scope.has("agroforestry")
  && measurements.exists(m, m.metric == "trees_planted" && m.value >= 500)

CEL context schema (v1)

Every CEL expression evaluates against a typed context. Each variable maps to data already present in the activity record and its linked records.

Custom functions on ScopeSet

Starter tag vocabulary

workScopeTag records are published as ATProto records that anyone can reference via strong references. Certified publishes curated tag sets for specific domains. Here's an example for regenerative work:

Anyone can create workScopeTag records for other domains. Communities don't write CEL by hand — the vocabulary powers a visual builder, and the structured expression gets generated behind the scenes.

Where CEL lives in the stack

CEL doesn't need to run onchain. The evaluation layer belongs alongside the ATProto infrastructure:

Further reading

• CEL specification
• Core Data Model — how records connect
• Activity Claim lexicon — the workScope field in context