Activity Claim

org.hypercerts.claim.activity

Overview#

An activity claim, also called a hypercert, describes a piece of work: what is being done or was done, by whom, when, and where. It is the record other records point to. Evidence, measurements, evaluations, funding receipts, and collections all refer to an activity to say which work they concern.

The record is the publisher's account of the work. It becomes more useful as others add evidence and assessments, but publishing it does not make its claims true. For the concepts behind it, see Activity Claims in the Guide.

How it's used#

• A project describes its work. A team publishes an activity for each distinct piece of work, such as one installation phase or six months of library maintenance, and groups related activities into a project with a collection.
• Others add context. Attachments, measurements, and evaluations published by the team or by other accounts link to the activity with a strong reference, so they stay tied to the version they concern.
• Funders record support. A funding receipt can name the activity it supported.
• Contributors are credited. The contributors array names the people or organizations involved, with optional weights and roles, either inline or through contribution records.

Only title, shortDescription, and createdAt are required. Start with those and add detail when it answers a real question for your users.

Schema#

Record key: any · Lexicon version: 1.6.0 · View the schema

Required properties#

Optional properties#

Definitions#

contributor

A contributor to the activity, with identity, weight, and contribution details.

contributorIdentity

Contributor information as a string (DID or identifier).

contributorRole

Contribution details as a string.

workScopeString

A free-form string describing the work scope for simple or legacy scopes.

Example#

A community energy project describing the installation phase of its solar array:

{
  "$type": "org.hypercerts.claim.activity",
  "title": "Solar array installation, phase 1",
  "shortDescription": "Installation of a 40 kW community-owned solar array on the village hall roof.",
  "description": {
    "$type": "org.hypercerts.defs#descriptionString",
    "value": "Phase 1 covers design, permits, and installation. Maintenance is described in a separate activity."
  },
  "contributors": [
    {
      "contributorIdentity": {
        "$type": "org.hypercerts.claim.activity#contributorIdentity",
        "identity": "did:plc:4yyb5gyoxl3sqdlqrvuxshkp"
      },
      "contributionWeight": "3",
      "contributionDetails": {
        "$type": "org.hypercerts.claim.activity#contributorRole",
        "role": "Project lead"
      }
    },
    {
      "contributorIdentity": {
        "$type": "org.hypercerts.claim.activity#contributorIdentity",
        "identity": "did:plc:ewvi7nxzyoun6zhxrhs64oiz"
      },
      "contributionWeight": "1",
      "contributionDetails": {
        "$type": "org.hypercerts.claim.activity#contributorRole",
        "role": "Electrical installation"
      }
    }
  ],
  "workScope": {
    "$type": "org.hypercerts.claim.activity#workScopeString",
    "scope": "Design, permitting, and installation of the rooftop array. Excludes ongoing maintenance."
  },
  "startDate": "2026-03-01T00:00:00.000Z",
  "endDate": "2026-06-30T00:00:00.000Z",
  "locations": [
    {
      "uri": "at://did:plc:4yyb5gyoxl3sqdlqrvuxshkp/app.certified.location/3lx2k7p4hvc2a",
      "cid": "bafyreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy"
    }
  ],
  "createdAt": "2026-07-02T09:15:00.000Z"
}

Rules and best practices#

• Say whether the work is planned, ongoing, or completed. The schema has no status field, so make it clear in the title, description, and dates. A plan and a report of completed work should not be mistaken for each other.
• Keep one activity per distinct piece of work. Smaller, well-scoped activities are easier to evaluate and fund than one broad claim. Use a collection to group them.
• Contribution weights are relative. contributionWeight is a positive number stored as a string. Weights don't need to sum to a total; applications normalize them if they need shares.
• Choose inline or referenced contributor details. Inline objects are simplest. Use a contributor information or contribution record when the same contributor or role is reused across activities.
• Use a plain-text work scope unless software needs to reason about it. The structured CEL form is for applications that compare or combine scopes; see Describing and Classifying Work.
• Strong references pin a version. locations and rights point to a specific version of the referenced record. If that record changes, update the reference to point at the new version.
• Editing changes the CID. Evaluations and other records that referenced the earlier version keep pointing to it. Readers should be told when an assessment concerns an older version; see Records That Change Over Time.
• Declare the text's language with langs. List up to three BCP-47 tags (such as es or pt-BR) for the language the author actually wrote in, and let the author correct it. Don't derive it from the interface language or a profile preference. Readers treat it as a hint: don't hide a record because it has no langs.

Related#

• Collection: group activities into a project or portfolio.
• Contribution: reusable contributor identity and role records.
• Attachment and Measurement: evidence and data about the work.
• Evaluation: assessments of the work.
• Funding Receipt: records of support for the work.
• Rights and Location: records the activity references.
• Guide: Activity Claims, A Shared Language.