A specialized vocabulary for agricultural commodities trading in decentralized knowledge graphs
The Skyocean Ontology is designed to facilitate global trade of agricultural commodities and traceable humanitarian donation programs with an emphasis on transparency, traceability, and efficient financing.
The core class representing a complete trade transaction between parties in the Skyocean ecosystem.
A specialized trade of agricultural commodities
Represents physical agricultural goods being traded in the Skyocean ecosystem
Entities involved in a trade transaction (buyer, seller, consignee, etc.)
Trade-related documentation including their verification status
Records of trade events recorded on the blockchain
Details of trade financing arrangements and token positions
Private data related to a trade transaction
Details of payment and financing arrangements for a trade
Types of documents required for the trade
Status information for required documents
Timeline information for the transaction
List of certifications or standards the commodity meets
Technical specifications of the commodity
Description of how the commodity is packaged
Detailed technical specifications with thresholds
Production method, origin, and other sensitive details
Method of payment (e.g., 'CAD' for Cash Against Documents)
Whether financing is required for the trade
An independent observation by an operational institution (port authority, customs authority, inspection agency, carrier, condition monitor, payment rail, financial institution, or human verifier) about a trade event. Each attestation is recorded as a Knowledge Asset and feeds the convergence record for its trade.
A record of an external signal confirming that payment has occurred, decoupled from the underlying rail. The same class represents signals from mobile money, national payment switches, regional settlement systems, SWIFT, letters of credit, cash-against-documents arrangements, on-chain escrow, and human-attested confirmations. Subclass of InstitutionalAttestation when the source is an institution.
The aggregate cross-validated state of a trade, constructed from the convergence of independent institutional attestations. Used to compute verification strength without a single central validator.
Category of institution making the attestation. Values: PortAuthority, CustomsAuthority, InspectionAgency, Carrier, ConditionMonitor, PaymentRail, FinancialInstitution, Human.
Name or identifier of the specific institution (e.g., 'Port of Tema', 'Ghana Revenue Authority', 'SGS', 'MTN MoMo').
Nature of the observation. Values: VesselCall, CargoHandling, CustomsClearance, QualityInspection, ConditionReading, Departure, PaymentConfirmation, IncidentReport, ClaimDecision, ComplianceVerification.
Time at which the attesting institution recorded the event.
Cryptographic signature or integrity hash of the attestation payload, used for audit and non-repudiation.
Reference to the Trade KA this attestation contributes to.
Classification of the payment signal source. Values: MobileMoney, NationalSwitch, RegionalSettlement, SWIFT, LetterOfCredit, CashAgainstDocuments, OnChainEscrow, HumanAttested.
Specific provider or network that emitted the confirmation (e.g., 'MTN MoMo', 'GhIPSS', 'PAPSS', 'Deutsche Bank AG').
External reference or transaction ID from the payment source (e.g., MoMo txn ID, SWIFT MT103 reference, LC number).
Monetary amount the source confirms as settled.
Total number of institutional attestations linked to the trade.
Number of distinct attesting institutions, used as a proxy for independence of the convergence record.
Computed score (0.0–1.0) summarising how strongly the trade is corroborated by independent institutional attestations.
Qualitative label derived from verificationStrength. Values: Insufficient, Partial, Strong, Full.
A cargo or marine insurance policy bound to one or more trades. Subclass of Document — the policy is itself a tradeable instrument with status, parties, and references — but carries dedicated insurance-specific properties.
An event affecting cargo that may trigger an insurance claim — damage, loss, theft, contamination, delay, casualty. The CargoIncident KA captures what happened, where, when, and to what extent, attested by an independent surveyor and/or the responsible custodian (port, carrier).
A formal claim filed against an InsurancePolicy in respect of a CargoIncident. Carries claim status, claimed amount, surveyor's loss assessment, insurer's decision, and payout details.
Insurer-issued policy reference (private layer — typically PII-adjacent).
Insurer or syndicate underwriting the policy (e.g., 'Lloyd's of London correspondent', 'Munich Re').
Type of insurance coverage. Values: Cargo, WarRisk, AllRisk, NamedPerils, Strike, ContingencyAndDelay.
Self-insured retention before the policy responds.
Nature of the incident. Values: Damage, Loss, Theft, Contamination, Delay, Casualty, GeneralAverage, Quarantine.
Where the incident occurred (UN/LOCODE port code, lat/long for in-transit, or place name).
Date and time the incident was reported or discovered.
Short descriptor of what happened (the private layer carries the full surveyor report text).
Quantity of cargo affected (with unit code).
Severity of loss. Values: Total, Partial, Constructive, Salvage, Marginal.
Reference to the InstitutionalAttestation issued by the independent loss adjuster / surveyor (attestorType: InspectionAgency, attestationType: IncidentReport).
Insurer-issued claim reference (private layer).
Reference to the InsurancePolicy under which this claim is filed.
Reference to the CargoIncident triggering the claim.
Status of the claim. Values: Filed, Acknowledged, UnderInvestigation, Approved, PartiallyApproved, Denied, Settled, Withdrawn.
Amount paid by the insurer (may differ from claim amount after surveyor adjustment and deductible).
Date funds were credited to the policyholder.
A summary of the logistics for a shipping leg of a trade — vessel, voyage, carrier, loading and discharge ports, BL reference, and container details. Attaches to a Trade via skyocean:logistics.
Reference from a Trade to its LogisticsRecord.
Vessel name (semantics align with GS1/DCSA vessel reference).
IMO ship identification number (7 digits) under the IMO ship-identification scheme.
Port of loading (UN/LOCODE plus place name).
Port of discharge (UN/LOCODE plus place name).
Bill of Lading reference number issued by the carrier.
Total container count for the shipping leg.
Container type description (e.g., '40-ft HC', 'flexitank-equipped 20-ft').
A typeable marker class indicating that a Trade KA is intended as a public-overview assertion (paired with a private TradePrivateData KA). Used as a secondary @type alongside skyocean:CommodityTrade.
Skyocean operating entity in the country of origin (Bill of Lading 'From'). Distinct from the legal Seller and from the fund-receiving entity.
Skyocean operating entity that receives institutional capital under the trade-finance facility (e.g., Skyocean DOOEL, Skyocean Lithuania UAB).
Trade corridor classification (e.g., 'Sudan', 'Ghana', 'EU').
Trade-structure classification (e.g., 'self-consignment-CAD', 'EXW-then-CFR-twoLeg').
Total cycle length in days (origination to settlement).
Ordered list of leg identifiers for a multi-leg trade (e.g., ['origin', 'export'] for an EXW-then-CFR cocoa-style structure). Single-leg trades typically omit this property.
Trade-level timeline block carrying expected dates (origination, shipment, arrival, settlement). Properties are typically drawn from the trade: sub-namespace.
Funding-branch classification per full-trade-flow.md. Values: 'A' (retail-only on-chain), 'B' (mixed institutional + retail on-chain), 'C' (institutional-only off-chain, no smart contract).
Payment-trigger classification used by the smart contract's _checkPaymentConditions evaluator. Values: 'OnDocumentsVerified', 'OnArrival', 'OnLoading', 'Manual'.
Reference from a child KA (FinancingRecord, Document, etc.) back to its parent Trade KA.
Reference from a Trade to one or more FinancingRecord KAs (institutional + retail per-holder).
Reference from a Trade to one or more PaymentSource KAs that confirm settlement on this trade.
Reference from a Trade to its ConvergenceRecord (or records, when multiple convergence events occur in a trade's lifecycle).
Composite block on a Trade describing its on-chain anchor — network, contract address, transaction hash. Optional and additive to skyocean:blockchainTransactionId.
Blockchain network identifier (e.g., 'polygon', 'polygon-mumbai').
Smart-contract address that issued the on-chain anchor (e.g., the SkyoceanTradeCore deployment).
Transaction hash of the createTrade call that issued the bytes32 tradeId. Distinct from skyocean:blockchainTransactionId, which is the tradeId itself.
Financing-source descriptor on a FinancingRecord. Values: 'institutional-trade-finance-facility', 'retail-skyt-capacity-activation', 'mixed-pool', 'institutional-tfa' (Branch C).
DID of the participant in this FinancingRecord — institutional facility DID or retail-holder DID.
ISO 17442 Legal Entity Identifier for an institutional participant (where applicable).
Number of distinct participants (used on retail-pool FinancingRecord roll-ups).
Capital amount provided by this participant (or retail-pool aggregate).
Share of total trade financing as a decimal (0.0–1.0).
Aggregate SKYT amount locked in a retail-pool FinancingRecord.
Indicative trade-cycle margin descriptor (string with explicit not-guaranteed framing) — e.g., '~3.8% per ~55-day cycle (Sudan corridor; not guaranteed)'.
SKYT amount locked by an individual retail holder for this trade.
USD-equivalent value of the SKYT locked by an individual retail holder.
Retail holder tier classification per Skyocean's tier model.
Wrapper carrying full supplier identification (schema:legalName, schema:address, schema:taxID, contact).
Wrapper carrying full buyer identification.
Wrapper carrying full participant identification on a private FinancingRecord (institutional or retail).
Wrapper carrying banking detail (schema:bankName, BIC/SWIFT identifier, schema:accountId).
Wrapper carrying the institutional financier's settlement account detail on the private FinancingRecord.
Wrapper carrying exact contract pricing (unit price + total contract value) on the private trade KA.
Reference to the executed Trade Finance Agreement governing an institutional FinancingRecord.
Internal Skyocean reference to the beneficial-ownership KYC dossier for an institutional financier.
Authorized signing officer for an institutional counterparty (name + role + DID).
Internal reference to a verified-wallet KYC linkage record for a retail holder.
Internal reference to the AML clearance record for a retail or institutional financier.
Internal reference to the sanctions screening record for a retail or institutional financier.
Type of government ID document on file for a retail holder. Values: 'passport', 'national-id', 'driver-licence'.
Internal Skyocean reference to the government-ID document record on file (the ID number itself is not stored as a literal).
ISO 3166 country code of a retail holder's jurisdiction of residence.
Quantity of the commodity (with schema:unitCode).
Country of origin of the commodity (ISO 3166 country name or code).
Country of destination of the commodity.
Date the trade was originated in the Skyocean platform.
Expected arrival date at discharge port.
Expected settlement (trade-completion) date.
A bounded humanitarian-aid campaign with a packing list, target amount, and delivery timeline. Identified by a backend-issued donation:campaignId (e.g. CMP-2026-SUD-001). Funding sources (wallets and/or bank accounts) are attached to the campaign and do not serve as its anchor.
A single donor contribution to a campaign, via stablecoin or bank transfer
A delivery event recording kits distributed to beneficiaries, verified by state officials
Private assertion data for a campaign: supplier details, distribution plan, bank account, and access permissions
Real-time signals from IoT sensors, partner confirmations, or field reports linked to a campaign
Specification of a kit's contents — food, medicine, prevention items — with quantities and sourcing details
Campaign status (Active, Funded, Procuring, Shipping, Delivered, Cancelled)
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.
One or more funding sources attached to the campaign — a wallet, bank account, or rail (Revolut, SEPA, SWIFT, stablecoin). Reuses skyocean:PaymentSource.
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.
Skyocean in-region entity that receives the goods on consignment (e.g. Skyocean Sudan for the Sudan pilot)
Campaign packing list (kits, quantities, specifications). Functional analog of a trade agreement in the core trading flow.
Public top-level cost summary surfaced to donors (e.g. kits vs operations)
Private detailed operational cost breakdown (freight, customs, insurance, last-mile logistics, platform & ops)
Reference to the parent campaign by donation:campaignId (and optionally KA UAL). Applies to contributions, distributions and supply-chain signals.
Payment rail: stablecoin, revolut, sepa, swift, other
Rail-specific payment record (provider, reference, institutional flag) reused from the core Skyocean payments module
On-chain transaction hash for stablecoin contributions
KYC attestation reference for the donor. Required for every contribution — no anonymous donations.
Public delivery outcome: delivered, partially-delivered, not-delivered, plus recipient category
Private. Number of families who received kits in a distribution event
Private. Number of kits delivered in a distribution event
State official, NGO or partner witness who confirmed distribution
Reference to an independent institutional attestation (customs, inspection, partner NGO) that feeds the convergence evaluator
Type of supply chain signal (IoT-Temperature, IoT-GPS, PartnerConfirmation, FieldReport, Verification)
ISO 6346 container identifier (e.g., 'MEDU 4471001'). Per-container — distinct from skyocean:containerCount which counts the set. Cross-document join key for graph linkage between BL, Packing List, Phyto, SGS, Customs etc.
Tamper-evident seal number affixed to a container at loading. One per container. Cross-document join key.
Production lot reference (e.g., 'AR-LOT-2026-00471'). Cross-document join key linking supplier invoice, packing list, phytosanitary, and quality cert.
IMO (International Maritime Organization) number — globally-unique 7-digit vessel identifier.
MMSI (Maritime Mobile Service Identity) — 9-digit vessel radio identifier used by AIS feeds.
Vessel name (e.g., 'MV BALTIC TRADER'). Use schema:name on a schema:Vehicle subclass when expressing in JSON-LD with schema.org context.
Carrier booking reference (e.g., 'MSCU-BK-2026-00471'). Cross-document join key linking BL to PO and IOM consolidation manifest.
Gross weight including packaging and pallets/dunnage, in kilograms. For cargo measurement; for full quantity context use schema:weight with QuantitativeValue.
Net weight of the cargo itself, excluding packaging, in kilograms.
Harmonized System (HS) commodity classification code, used in customs declarations. Format like '0713.40.00'.
Phytosanitary / disinfestation treatment method applied to the cargo (e.g., 'Methyl bromide fumigation, 48 mg/L for 24 h at 21°C').
Date the phytosanitary / disinfestation treatment was applied.
Sampling method used by the inspection agency (e.g., 'ISO 24333:2009, composite sample of 30 incremental samples per container').
Composite quality test results (parameter, measured value, spec, pass/fail). Free-form string in v2.1.3; future versions may model as a structured assertion.
EDIFACT message type used in the customs filing (e.g., 'CUSDEC', 'CUSRES', 'CUSCAR', 'IFTSTA', 'COARRI', 'COPRAR', 'CODECO').
Outcome reference of the EDIFACT exchange (e.g., the response message ID or 'CUSRES accepted').
Unique End-to-end Transaction Reference (UETR) from a SWIFT MT103 message — UUID format. Cross-document join key linking inbound payment confirmation to invoice and PO.
SWIFT MT103 Field 20 — sender's transaction reference. Often carries the buyer's PO number.
SWIFT MT103 Field 70 — reference for the beneficiary. Typically carries the trade ID + invoice reference.
Insured value declared on the marine cargo / war-risk policy, typically 110% of CIF/CFR per ICC(A) standard. Use schema:price with currency for the JSON-LD value object.
Premium paid to bind the policy. Use schema:price with currency for the JSON-LD value object.
A single AIS position report from a vessel during a tracked voyage. A continuous AIS feed comprises many VesselPosition assertions.
Timestamp of the AIS position report (ISO 8601 UTC).
Course over ground in degrees (COG, 0–359°).
AIS navigational status (e.g., 'Underway using engine', 'At anchor', 'Moored').
Total number of AIS position pings captured for a tracked voyage. Used in the AIS feed Document KA to summarize feed density.
Legal entity acting as the EUDR Operator that places the relevant commodity on the EU market and submits the Due Diligence Statement under Regulation (EU) 2023/1115.
EU Information System reference number for the submitted EUDR Due Diligence Statement.
A geolocated plot of land where a regulated commodity (e.g., cocoa, coffee, palm oil, soy) was produced. Required under EUDR for parcel-level traceability. Geometry expressed via GeoJSON polygon and centroid.
GeoJSON polygon or multipolygon describing the plot boundary.
Centroid latitude/longitude of the plot, WGS84 — convenience field for indexing.
Verification that a production plot was deforestation-free as of the EUDR cut-off date (31 December 2020) per remote-sensing analysis. Values: 'Verified', 'NotVerified', 'AtRisk'.
Container-level temperature + humidity telemetry log captured by an in-container data logger across a voyage.
Serial number of the temperature/humidity logger device (e.g., 'STM-44511-A').
Model designation of the data logger device (e.g., 'Sensitech TempTale GEO 4').
Logger sampling interval as ISO 8601 duration (e.g., 'PT15M' = 15 minutes).
Min–max temperature range observed across the voyage, in degrees Celsius.
Min–max relative humidity range observed across the voyage (% RH).
Number of temperature excursion events outside spec tolerance during the voyage. 0 = within tolerance.
Pointer to the original document file in private storage (e.g., S3 signed URL). Always private-tier — never appears in a Document KA's public assertion. Equivalent to schema:url qualified with skyocean:visibility 'private'.
Per-rail aggregate of donor contributions for a campaign (e.g., total stablecoin / SEPA / SWIFT for CMP-2026-SUD-001). Issued continuously as contributions arrive; final aggregate at campaign close. Public-tier shows totals; private-tier links per-contribution detail.
The receiving rail used for an aggregate or single contribution: 'stablecoin', 'sepa', 'swift', 'revolut'.
Total contribution amount across the rail at the time of receipt issuance.
Number of distinct contributors on the rail at the time of receipt issuance. Private-tier — donor identities never surface; counts may.
Independent observation of a donation distribution event by an external NGO or partner agency (e.g., IOM Sudan country office). Distinct from donation:DonationDistribution which is the operational delivery record; this class captures the third-party witness.
Distribution acknowledgment from the in-region last-mile coordinator (e.g., Khartoum State Ministry of Social Welfare). State-authority sign-off on receipt and onward distribution to identified beneficiary households.
Skyocean operating entity that operates the donation campaign (e.g., Skyocean DOOEL — campaign operator and fund-receiving entity). Distinct from the consignee that takes title in the destination country.
Public-tier description of which receiving rails the campaign accepts (e.g., 'Stablecoin receiving wallet (USDC/USDT) · SEPA donation account · SWIFT correspondent'). Reveals channels, not donor identities.