Schema & context

How Skyocean combines standards and custom vocabulary for Knowledge Assets.

Strategy

We use a hybrid approach: existing standards as the foundation, Skyocean ontology only where standards don't cover our needs.

  • Schema.org — Organizations, people, addresses, prices, dates, identifiers, quantities.
  • GS1 — Trade items, HS codes, locations, events, Incoterms.
  • Skyocean — Trade lifecycle, financing, verification, document status, token operations, compliance.
  • OriginTrail (ot) — DKG metadata: assertion ID, timestamp, version, UAL.

Schema map — core

The classes that every Skyocean trade KA touches and how they relate. Skyocean-specific terms are skyocean:*; international standards (schema:*, gs1:*) are used wherever they exist.

classDiagram
    direction LR

    Trade <|-- CommodityTrade
    Trade <|.. PublicTradeOverview : marker
    Trade *-- Commodity : commodity
    Trade o-- TradeParty : shipper / consignee / seller / buyer / supplier
    Trade *-- LogisticsRecord : logistics
    Trade *-- FinancingRecord : financing
    Trade *-- TradePrivateData : private layer
    Trade *-- PaymentDetails : payment

    Document --> Trade : relatedTrade
    Document --> TradeParty : issuer / attestor
    Document --> Commodity : commodityRef
    Document --> Document : sharesIdentifier

    LogisticsRecord *-- VesselPosition : positions
    Document *-- ColdChainLog : telemetry
    Document *-- ProductionPlot : EUDR plot

    InsurancePolicy --> Trade : covers
    CargoIncident --> Trade : occurredIn
    InsuranceClaim --> InsurancePolicy : claims
    InsuranceClaim --> CargoIncident : forIncident

    class Trade {
        +tradeId
        +tradeStatus
        +corridor
        +incoterms
        +cycleDays
    }
    class Document {
        +documentNumber
        +documentStatus
        +issueDate
        +containerNumber
        +sealNumber
        +lotReference
        +bookingReference
        +documentURL : private
    }
    class TradeParty {
        +did
        +role
        +legalDetails : private
    }
    class VesselPosition {
        +imoNumber
        +mmsiNumber
        +positionLat
        +positionLon
        +navStatus
    }
    class ProductionPlot {
        +plotGeometry
        +plotCentroid
        +cutoffCompliance
    }
    class ColdChainLog {
        +loggerSerial
        +temperatureRange
        +temperatureExcursion
    }

Composition (*--) means the parent owns the child as part of its public/private split. Reference (-->) means the child carries an identifier pointing back. sharesIdentifier is the cross-document edge — Documents that share container numbers, seal numbers, lot references, BL numbers, or SWIFT UETRs link to each other automatically; that's how multi-source convergence emerges as a graph rather than as anchor-only spokes.

Schema map — donation specialization

Humanitarian aid campaigns reuse the same Trade backbone with a donation-specific layer (donation:*) for donor receipts, distribution observations, and last-mile acknowledgments.

classDiagram
    direction LR

    Trade <|-- DonationCampaign

    DonationCampaign *-- DonationContribution : contributions
    DonationCampaign *-- DonationDistribution : distributions
    DonationCampaign *-- DonorAggregateReceipt : per rail
    DonationContribution --> PaymentSource : viaRail
    DonationDistribution <-- DistributionObservation : observed by
    DonationDistribution <-- LastMileAcknowledgment : ackd by

    class DonationCampaign {
        +campaignId
        +goods
        +targetFunding
        +raised
        +sourceOfFunds
        +cycleDays
    }
    class DonationContribution {
        +contributionRail
        +amount
        +kycRef : private
        +onChainTxHash
    }
    class DonationDistribution {
        +deliveryStatus
        +familiesServed : private
        +kitsDistributed : private
        +verifiedBy
    }
    class DonorAggregateReceipt {
        +contributionRail
        +aggregateAmount
        +contributorCount : private
    }
    class DistributionObservation {
        +observerDID
        +observationDate
        +verificationMethod
    }
    class LastMileAcknowledgment {
        +coordinatorDID
        +acknowledgmentDate
        +stateAuthorityRef
    }

A campaign's audit story converges across six independently-issued attestations: supplier invoice → IOM consolidation manifest → BL → customs → distribution observation (independent NGO) → state acknowledgment. No single party controls the chain.

In practice — canonical lentils trade

How SKY-2026-00471 (Argentina → Sudan, 500 MT lentils) actually instantiates the schema. The cross-document edges (dashed) form via shared identifiers: container series MEDU 4471001-020, lot reference AR-LOT-2026-00471, BL MSCU-MAR-2026-00471.

graph LR
    A((SKY-2026-00471
CommodityTrade)):::anchor

    A --> BL[Bill of Lading
MSCU-MAR-2026-00471]:::doc
    A --> SI[Supplier Invoice
AR-SUP-INV]:::doc
    A --> PHY[Phytosanitary
AR-FITO-44712]:::doc
    A --> SGS[SGS Quality
SGS-AR-INSP-44712]:::doc
    A --> CUS[Argentina CUSDEC
AR-AFIP-DESP]:::doc
    A --> PAY[Buyer Payment
SWIFT MT103]:::doc

    A --> P1[Skyocean Argentina
shipper]:::party
    A --> P2[Skyocean Sudan
consignee]:::party
    A --> P3[Argentine Lentil Coop
supplier]:::party
    A --> P4[MSC Carrier]:::party
    A --> P5[SENASA]:::party

    BL --> P4
    BL --> P1
    BL --> P2
    SI --> P3
    SI --> P1
    PHY --> P5

    BL -. "MEDU 4471001 to 020" .- PHY
    BL -. "MEDU 4471001 to 020" .- SGS
    BL -. "MEDU 4471001 to 020" .- CUS
    SI -. "AR-LOT-2026-00471" .- PHY
    SI -. "AR-LOT-2026-00471" .- SGS
    PAY -. "SKY-INV-2026-00471" .- SI

    classDef anchor fill:#0066FF,stroke:#00D4FF,stroke-width:3px,color:#fff
    classDef doc fill:#142238,stroke:#4D94FF,color:#E8EDF5
    classDef party fill:#1a2940,stroke:#8FA3BF,color:#E8EDF5

Solid edges (→) are direct anchor / issuer relationships. Dashed edges with labels are cross-document convergence — these emerge automatically because the documents independently reference the same container range, lot, or invoice ID. An auditor can walk this graph in any direction and verify that 6 independently-issued documents all agree on the same physical shipment.

Base context

All Skyocean Knowledge Assets use this @context in JSON-LD:

{
  "@context": {
    "schema": "http://schema.org/",
    "gs1": "https://gs1.org/voc/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "skyocean": "https://skyocean.io/ontology/",
    "ot": "https://ontology.origintrail.io/dkg/1.0#"
  }
}

Resources