Skip to content

docs: rename CEL Work Scopes → Work Scopes, trim and restructure #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
s-adamantine wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: rename CEL Work Scopes → Work Scopes, trim and restructure #66

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b5734c8
docs: rename CEL Work Scopes to Work Scopes, trim speculative content…
s-adamantine Mar 3, 2026
a8d3f0e
docs: restore original motivation paragraph for structured scopes
s-adamantine Mar 3, 2026
9b17e83
docs: single CEL link in intro, remove redundant CEL links and paragr…
s-adamantine Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 28 additions & 49 deletions pages/core-concepts/cel-work-scopes.md → pages/core-concepts/work-scopes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,31 @@
---
title: CEL Work Scopes
description: How CEL (Common Expression Language) makes hypercert work scopes machine-readable, composable, and queryable.
title: Work Scopes
description: How work scopes make hypercerts machine-readable, composable, and queryable.
---

# CEL Work Scopes
# 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.
Work scopes describe what work a hypercert covers. Every activity claim has a `workScope` field that can be either a simple string list or a structured CEL expression for machine-evaluable logic.

[CEL (Common Expression Language)](https://github.com/google/cel-spec) 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.
## The simple case

## Why structured scopes matter
Most hypercerts use a simple string list for work scopes:

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.
```json
{
"workScope": { "allOf": ["Documentation", "Open Source"] }
}
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Align workScope shape terminology with the union schema.

Line 8/12 says “simple string list,” Lines 14-17 show an allOf object, and Lines 90-94 define workScopeString as free-form string. These three representations conflict and can cause incorrect client implementations. Please normalize wording/examples to one canonical simple variant (or explicitly document all accepted variants and their exact schema).

Also applies to: 90-94

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@pages/core-concepts/work-scopes.md` around lines 8 - 17, Normalize the
documentation and examples so the `workScope` simple variant and the union
schema match: pick one canonical simple shape (either a plain array of strings
like `"workScope": ["Documentation","Open Source"]` or an object with `allOf`)
and update the example block and descriptive text to use that exact form;
alternatively, explicitly list all accepted variants and their exact schemas,
referencing the union member names `workScopeString` and the structured CEL
variant (e.g., `workScopeCEL`/`allOf`) and show one concrete example for each so
clients can implement the union correctly.

```

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.
This is what the [Quickstart](/getting-started/quickstart) uses. It's human-readable and sufficient for many use cases.

## Architecture: two layers
## Why structured scopes matter

The design uses two complementary layers:
Simple string lists work for individual hypercerts, but they're hard to query at scale. As the network grows, connecting funders to relevant work, detecting overlapping claims, and matching evaluators to their domains all require machine-readable structure. Free-form text is legible to a person reading one claim at a time — it's invisible to any system trying to operate across thousands of claims.

## CEL architecture

[CEL (Common Expression Language)](https://github.com/google/cel-spec) is an open-source expression language for evaluating conditions in distributed systems. 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").
Expand Down Expand Up @@ -129,49 +137,20 @@ The `workScope` field on `org.hypercerts.claim.activity` accepts two variants:

## What CEL unlocks

### Funder matching

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

```cel
// "All mangrove work in East Africa"
scope.has("mangrove_restoration") && location.country in ["KE", "TZ", "MZ", "MG"]
```
{% callout type="note" %}
The CEL evaluation runtime is planned. The lexicon schemas are defined, but appview-side evaluation is not yet implemented.
{% /callout %}

### Evaluation matching
Once the evaluation runtime is in place, structured scopes enable:

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

```cel
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:

```cel
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:

```cel
// "Agroforestry that planted 500+ verified trees"
scope.has("agroforestry")
&& measurements.exists(m, m.metric == "trees_planted" && m.value >= 500)
```
- **Funder matching** — funders define criteria as CEL expressions, and the appview matches them against existing hypercerts automatically.
- **Evaluation matching** — evaluators express their domain expertise as CEL conditions, and the system surfaces relevant claims for review.
- **Overlap detection** — when a new hypercert is created, CEL can check whether the claimed work scope overlaps with existing claims in the same time and location.
- **Measurement-based queries** — because CEL can access linked measurement records, queries can go beyond tags (e.g., "agroforestry projects that planted 500+ verified trees").

## 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.
This schema is planned — it defines the runtime context that appviews will provide when evaluating CEL expressions. Every CEL expression evaluates against a typed context. Each variable maps to data already present in the activity record and its linked records.

| Variable | Type | Source | Description |
|----------|------|--------|-------------|
Expand All @@ -193,7 +172,7 @@ Every CEL expression evaluates against a typed context. Each variable maps to da

## Starter tag vocabulary

`workScopeTag` records are published as ATProto records that anyone can reference via strong references. [Certified](https://certified.ink) publishes curated tag sets for specific domains. Here's an example for regenerative work:
`workScopeTag` records are published as ATProto records that anyone can reference via strong references. [Certified](https://certified.app) publishes curated tag sets for specific domains. Here's an example for regenerative work:

| Domain | Example tags |
|--------|-------------|
Expand Down