Donation Extension - Skyocean Ontology

Overview

The Donation Extension adapts the Skyocean commodity trading model to humanitarian aid campaigns. Rather than a trade between buyer and seller, the donation model anchors around a donation:DonationCampaign identified by a backend-issued donation:campaignId (e.g. CMP-2026-SUD-001). A campaign aggregates contributions from many donors across one or more funding sources (stablecoin wallets, bank accounts, or both), funds procurement and shipping, and closes when distribution is verified in the field.

Structurally a donation is a humanitarian supply chain: the same institutional attestations, customs readiness, and convergence-based verification that underpin a commercial trade apply, the only difference is that there is no repayment obligation to the donor. Donation flows therefore sit on the same DKG graph as trading flows and can share institutional events, documents, and payment-source records.

Every donation campaign is published as a Knowledge Asset (KA) on the OriginTrail DKG, with public assertions for accountability and private assertions for personally identifiable information (PII) of beneficiaries, KYC'd donors and detailed operational cost breakdowns.

This extension is designed for Skyocean's Sudan humanitarian pilot (2026) but applies to any campaign-based aid program where donors, procurement, logistics and distribution need to be verifiable end-to-end.

Backend key as canonical anchor

The campaign's canonical identifier is the backend-issued donation:campaignId, never a wallet address. A campaign can be fully off-chain (bank-only), fully on-chain, or mixed. Wallets and bank accounts are listed as funding sources attached to the campaign, not as its anchor. No smart contract is required to launch a campaign.

Reuses core trading ontology

Donation classes inherit from skyocean: structures where possible (Document, Party, Location, PaymentSource, InstitutionalAttestation, ConvergenceRecord) so that donation flows and trading flows share the same graph and interoperate natively.

Classes

Six classes compose the donation extension. Each is a top-level Knowledge Asset type on the DKG.

donation:DonationCampaign

A humanitarian-aid campaign identified by a backend-issued donation:campaignId, with a packing list (kits, quantities, specifications), a target amount, target beneficiaries, a region and one or more funding sources (wallets and/or bank accounts). Acts as the anchor KA that links all contributions, procurement, shipping and distribution KAs.

Parent: schema:Project
Status: testing

donation:DonationContribution

An individual donation made to a campaign. Supports stablecoin (Polygon, USDC/USDT) and bank rails (Revolut, SEPA, SWIFT). All contributions are KYC'd per jurisdictional requirements, no anonymous donations.

Parent: schema:MonetaryDonation
Status: testing

donation:DonationDistribution

A verified distribution event at a beneficiary location: families served, kits delivered, witness / partner verification, and geo-referenced signal evidence.

Parent: skyocean:Delivery
Status: testing

donation:DonationCampaignPrivate

Private assertion attached to a campaign KA. Holds beneficiary PII, KYC'd donor identities and other sensitive fields that must not appear on the public graph.

Parent: skyocean:PrivateAssertion
Status: testing

donation:SupplyChainSignal

A timestamped event on the supply chain: contribution received, procurement signed, shipment handed over, customs cleared, last-mile handover, distribution verified. Used to reconstruct the full campaign timeline.

Parent: schema:Event
Status: testing

donation:DonationKit

A standardized aid kit (e.g. family medical + water purification kit). Describes composition, unit cost, supplier and certification, and is referenced by procurement and distribution events.

Parent: schema:Product
Status: testing

Properties

Properties are qualified with the donation: namespace. Types refer to XSD datatypes or to classes in skyocean:, schema: or donation:. Where a suitable schema.org standard property already exists (e.g. schema:validThrough), it is reused directly rather than minting a bespoke donation: term, standards-first vocabulary discipline.

Property	Domain	Range	Description
`donation:campaignId`	`DonationCampaign`	`xsd:string`	Canonical anchor identifier for the campaign, issued by the Skyocean backend (e.g. `CMP-2026-SUD-001`). Stable across on-chain and off-chain campaigns.
`donation:status`	`DonationCampaign`	`xsd:string`	Campaign state: draft, active, funded, procurement, in-transit, distributing, closed, cancelled.
`schema:validThrough`	`DonationCampaign`	`xsd:dateTime`	Optional. Campaign end date / funding deadline, after which the campaign no longer accepts contributions. Reused schema.org standard property (not a bespoke `donation:` term). Mirrors `trades.valid_through` in the backend per the DB-mirrors-KA invariant (doctrine #102). Populated at campaign creation from the Donation Agreement digest, or by operator input; `NULL` when neither is present.
`donation:targetAmount`	`DonationCampaign`	`schema:MonetaryAmount`	Fundraising goal for the campaign, in the stated currency (EUR/USD/USDC by default).
`donation:currentAmount`	`DonationCampaign`	`schema:MonetaryAmount`	Running total received from all contributions (on-chain + off-chain reconciled).
`donation:fundingSource`	`DonationCampaign`	`skyocean:PaymentSource`	One or more funding sources attached to the campaign, a wallet, bank account, or rail (Revolut, SEPA, SWIFT, stablecoin). A campaign may list any combination.
`donation:campaignWallet`	`DonationCampaign`	`xsd:string`	Optional. EVM wallet address (e.g. Polygon) when the campaign has an on-chain funding source. Not the anchor identifier, some campaigns are fully off-chain.
`donation:consignedTo`	`DonationCampaign`	`skyocean:Party`	Skyocean in-region entity that receives the goods on consignment (e.g. Skyocean Sudan for the Sudan pilot).
`donation:contributorCount`	`DonationCampaign`	`xsd:integer`	Number of unique contributions received by the campaign.
`donation:targetBeneficiaries`	`DonationCampaign`	`xsd:integer`	Planned number of beneficiaries (e.g. families, individuals) the campaign intends to serve.
`donation:region`	`DonationCampaign`	`schema:Place`	Geographic region the campaign serves (state / province level for the Sudan pilot).
`donation:packingList`	`DonationCampaign`	`donation:DonationKit`	The campaign's core packing list, kits, quantities and specifications. Functional analog of a trade agreement in the core trading flow.
`donation:costSummary`	`DonationCampaign`	`schema:MonetaryAmount`	Public. Top-level cost summary surfaced to donors (e.g. €75,000 kits, €25,000 operations).
`donation:operationalCostBreakdown`	`DonationCampaignPrivate`	`schema:MonetaryAmount`	Private. Detailed ops breakdown (freight, customs, insurance, last-mile logistics, platform & ops). Not published publicly to preserve negotiating position with suppliers.
`donation:campaignRef`	`DonationContribution, DonationDistribution, SupplyChainSignal`	`DonationCampaign`	Reference to the parent campaign, resolved by `donation:campaignId` and optionally the KA UAL.
`donation:method`	`DonationContribution`	`xsd:string`	Payment method / rail: stablecoin, revolut, sepa, swift, other.
`donation:paymentSource`	`DonationContribution`	`skyocean:PaymentSource`	The rail-specific payment record (provider, reference, institutional flag) reused from the core Skyocean payments module.
`donation:onChainTxHash`	`DonationContribution`	`xsd:string`	Transaction hash if the contribution was made on-chain.
`donation:kycRef`	`DonationContribution`	`xsd:string`	Reference to the KYC attestation for this donor. Required for every contribution, no anonymous donations.
`donation:deliveryStatus`	`DonationDistribution`	`xsd:string`	Public. Delivery outcome: delivered, partially-delivered, not-delivered, plus the recipient category (beneficiary group / partner).
`donation:familiesServed`	`DonationDistribution`	`xsd:integer`	Private. Number of families served in a verified distribution event (detailed counts kept internal for operational optimization).
`donation:kitsDistributed`	`DonationDistribution`	`xsd:integer`	Private. Number of `DonationKit` units delivered in the distribution event.
`donation:verifiedBy`	`DonationDistribution`	`skyocean:Party`	Party that verified the distribution on the ground (NGO, state partner, witness).
`donation:attestationRef`	`DonationDistribution`	`skyocean:InstitutionalAttestation`	Reference to an independent institutional attestation (customs, inspection, partner NGO) that feeds the convergence evaluator.
`donation:signalType`	`SupplyChainSignal`	`xsd:string`	Type of supply-chain signal: contribution, procurement, shipment, customs, handover, distribution.

Vocabulary Terms

Donation Campaign Status

draft, Campaign created, not yet active
active, Accepting contributions
funded, Target amount reached
procurement, Funds deployed to suppliers
in-transit, Goods moving through corridor
distributing, Last-mile delivery in progress
closed, Distribution verified, campaign closed
cancelled, Campaign cancelled, refunds issued

Supply Chain Signal Types

contribution, A new donation was received
procurement, A purchase order was signed with a supplier
shipment, Goods handed to the logistics provider
customs, Customs cleared at origin / destination
handover, Handed to in-country partner
distribution, Verified distribution to beneficiaries

Examples

Donation Campaign (JSON-LD)

{
  "@context": {
    "schema": "https://schema.org/",
    "skyocean": "https://skyocean.io/ontology/",
    "donation": "https://skyocean.io/ontology/donation/"
  },
  "@type": "donation:DonationCampaign",
  "@id": "did:dkg:polygon:137/0x.../12345",
  "donation:campaignId": "CMP-2026-SUD-001",
  "schema:name": "Sudan Emergency Medical Kits, Khartoum State",
  "schema:description": "1,000 family kits (medical + water purification) for displaced families.",
  "donation:status": "active",
  "donation:consignedTo": {
    "@type": "skyocean:Party",
    "schema:name": "Skyocean Sudan"
  },
  "donation:fundingSource": [
    {
      "@type": "skyocean:PaymentSource",
      "skyocean:rail": "stablecoin",
      "skyocean:provider": "Polygon",
      "skyocean:reference": "0xabc...def",
      "skyocean:institutional": false
    },
    {
      "@type": "skyocean:PaymentSource",
      "skyocean:rail": "sepa",
      "skyocean:provider": "Revolut",
      "skyocean:reference": "LT00 0000 0000 0000 0001",
      "skyocean:institutional": false
    },
    {
      "@type": "skyocean:PaymentSource",
      "skyocean:rail": "swift",
      "skyocean:provider": "Revolut",
      "skyocean:reference": "REVOLT21 / LT00 0000 0000 0000 0001",
      "skyocean:institutional": false
    }
  ],
  "donation:campaignWallet": "0xabc...def",
  "donation:targetAmount": {
    "@type": "schema:MonetaryAmount",
    "schema:currency": "EUR",
    "schema:value": 100000
  },
  "donation:currentAmount": {
    "@type": "schema:MonetaryAmount",
    "schema:currency": "EUR",
    "schema:value": 18450
  },
  "donation:costSummary": [
    { "@type": "schema:MonetaryAmount", "schema:name": "Kits", "schema:currency": "EUR", "schema:value": 75000 },
    { "@type": "schema:MonetaryAmount", "schema:name": "Operations", "schema:currency": "EUR", "schema:value": 25000 }
  ],
  "donation:contributorCount": 147,
  "donation:targetBeneficiaries": 1000,
  "donation:packingList": {
    "@type": "donation:DonationKit",
    "schema:name": "Family Medical + Water Purification Kit",
    "schema:numberOfItems": 1000
  },
  "donation:region": {
    "@type": "schema:Place",
    "schema:name": "Khartoum State, Sudan"
  }
}

Donation Contribution, Stablecoin (JSON-LD)

{
  "@context": {
    "schema": "https://schema.org/",
    "skyocean": "https://skyocean.io/ontology/",
    "donation": "https://skyocean.io/ontology/donation/"
  },
  "@type": "donation:DonationContribution",
  "donation:campaignRef": "CMP-2026-SUD-001",
  "donation:method": "stablecoin",
  "donation:paymentSource": {
    "@type": "skyocean:PaymentSource",
    "skyocean:rail": "stablecoin",
    "skyocean:provider": "Polygon",
    "skyocean:reference": "0x7f3...a21",
    "skyocean:institutional": false
  },
  "donation:onChainTxHash": "0x7f3...a21",
  "donation:kycRef": "kyc:sumsub:applicant:9f21ae3c",
  "schema:amount": {
    "@type": "schema:MonetaryAmount",
    "schema:currency": "USDC",
    "schema:value": 250
  },
  "schema:dateCreated": "2026-04-10T14:22:00Z"
}

Donation Contribution, Bank rail (JSON-LD)

{
  "@context": {
    "schema": "https://schema.org/",
    "skyocean": "https://skyocean.io/ontology/",
    "donation": "https://skyocean.io/ontology/donation/"
  },
  "@type": "donation:DonationContribution",
  "donation:campaignRef": "CMP-2026-SUD-001",
  "donation:method": "sepa",
  "donation:paymentSource": {
    "@type": "skyocean:PaymentSource",
    "skyocean:rail": "sepa",
    "skyocean:provider": "Revolut",
    "skyocean:reference": "REV-2026-04-10-08871",
    "skyocean:institutional": false
  },
  "donation:kycRef": "kyc:smileid:applicant:12c4f7a0",
  "schema:amount": {
    "@type": "schema:MonetaryAmount",
    "schema:currency": "EUR",
    "schema:value": 500
  },
  "schema:dateCreated": "2026-04-11T09:05:00Z"
}

Supply Chain Signal (JSON-LD)

{
  "@context": {
    "schema": "https://schema.org/",
    "skyocean": "https://skyocean.io/ontology/",
    "donation": "https://skyocean.io/ontology/donation/"
  },
  "@type": "donation:SupplyChainSignal",
  "donation:signalType": "distribution",
  "donation:campaignRef": "CMP-2026-SUD-001",
  "donation:attestationRef": {
    "@type": "skyocean:InstitutionalAttestation",
    "skyocean:attestor": "Partner NGO, Omdurman",
    "skyocean:attestationType": "last-mile-handover"
  },
  "schema:location": {
    "@type": "schema:Place",
    "schema:name": "Omdurman, Distribution Point 3",
    "schema:geo": { "@type": "schema:GeoCoordinates", "schema:latitude": 15.65, "schema:longitude": 32.48 }
  },
  "schema:startDate": "2026-05-18T09:00:00Z"
}

Donation Ontology Extension