"$schema": https://json-schema.org/draft/2020-12/schema
title: Shipper's Letter of Instructions
description: A document issued by a shipper to a freight forwarder authorising them to arrange shipment and providing all necessary instructions for handling, documentation, and delivery of the consignment.
type: object
required:
  - "@context"
  - type
  - credentialSchema
  - validTo
  - issuer
  - credentialSubject
properties:
  "@context":
    type: string
    format: uri
    description: 'Linked Data context for semantic interoperability'
    const: "https://un.opensource.unicc.org/unece/uncefact/spec-unvtd/shippers-letter-of-instructions-context.json"
  type:
    type: array
    description: 'Document types'
    items:
      type: string
      enum:
        - VerifiableCredential
        - ShippersLetterOfInstructions
    minItems: 2
    maxItems: 2
    example:
      - VerifiableCredential
      - ShippersLetterOfInstructions
  credentialSchema:
    type: object
    description: 'Reference to the credential schema for validation'
    properties:
      id:
        type: string
        format: uri
        const: "https://un.opensource.unicc.org/unece/uncefact/spec-unvtd/shippers-letter-of-instructions-schema.yaml"
        description: 'Public location of the schema'
      type:
        type: string
        const: "JsonSchema"
        description: 'Schema type identifier'
    required:
      - id
      - type
  id:
    type: string
    format: uri
    description: 'Unique identifier for the credential'
    example: "urn:uuid:a3c19de2-7f84-4b22-bc91-1047d8e3f201"
  validFrom:
    example: 2025-03-06T10:00:00Z
    type: string
    format: date-time
    description: 'Credential validity start date'
  validTo:
    example: 2026-03-06T10:00:00Z
    type: string
    format: date-time
    description: 'Credential validity end date'
  issuer:
    description: 'Identifier of the shipper issuing the letter of instructions (e.g., DID)'
    type: string
    format: uri
    example: did:web:surfpro.example.com
  credentialSubject:
    description: 'Shipper letter of instructions details'
    type: object
    properties:
      issueDate:
        example: '2025-03-06T00:00:00Z'
        type: string
        format: date-time
        description: Date that the letter of instructions was issued.
      despatchDate:
        example: '2025-03-10T00:00:00Z'
        type: string
        format: date-time
        description: Date on which goods are, or are expected to be, despatched or consigned.
      documentaryCreditNumber:
        example: LC-2025-HSBC-00432
        type: string
        description: Reference number to identify a documentary credit (letter of credit).
      incoterms:
        example: FOB Gold Coast, Australia
        type: string
        description: Free form description of delivery or transport terms (Incoterms).
      handlingInstructions:
        example: "Handle with care. Keep dry. Do not stack more than 3 high."
        type: string
        description: Free form description of a set of handling instructions for the goods or packages.
      insuranceCondition:
        example: "Institute Cargo Clauses (A) - All Risks"
        type: string
        description: Reference to the general conditions of contract under which insurance coverage applies.
      authentication:
        example: "Signed by the authorised representative of SurfPro Manufacturing Inc."
        type: string
        description: Proof that the document has been authenticated.
      consignor:
        description: Party consigning goods as stipulated in the transport contract by the party ordering transport.
        type: object
        properties:
          type:
            type: string
            default: Consignor
            enum:
            - Consignor
          id:
            example: did:web:surfpro.example.com
            type: string
            format: uri
            description: A unique party identifier.
          name:
            example: SurfPro Manufacturing Inc.
            type: string
            description: Trade party name.
          street:
            example: 150 Industrial Drive
            type: string
            description: The street component of the address.
          city:
            example: Gold Coast
            type: string
            description: The city component of the address.
          state:
            example: QLD
            type: string
            description: The state component of the address.
          zip:
            example: 4217
            type: number
            description: Postal code.
          country:
            example: AU
            type: string
            description: Country.
      consignee:
        description: Party to which goods are consigned.
        type: object
        properties:
          type:
            type: string
            default: Consignee
            enum:
            - Consignee
          id:
            example: did:web:waveridersupplies.example.com
            type: string
            format: uri
            description: A unique party identifier.
          name:
            example: Wave Rider Supplies, Inc
            type: string
            description: Trade party name.
          street:
            example: 210 Ocean Boulevard
            type: string
            description: The street component of the address.
          city:
            example: Los Angeles
            type: string
            description: The city component of the address.
          state:
            example: CA
            type: string
            description: The state component of the address.
          zip:
            example: 90001
            type: number
            description: Postal code.
          country:
            example: US
            type: string
            description: Country.
      freightForwarder:
        description: Party undertaking the forwarding of goods.
        type: object
        properties:
          type:
            type: string
            default: FreightForwarder
            enum:
            - FreightForwarder
          id:
            example: did:web:globalfreight.example.com
            type: string
            format: uri
            description: A unique party identifier.
          name:
            example: Global Freight Solutions Pty Ltd
            type: string
            description: Trade party name.
          street:
            example: 88 Harbour View Road
            type: string
            description: The street component of the address.
          city:
            example: Brisbane
            type: string
            description: The city component of the address.
          state:
            example: QLD
            type: string
            description: The state component of the address.
          zip:
            example: 4000
            type: number
            description: Postal code.
          country:
            example: AU
            type: string
            description: Country.
      buyer:
        description: Party to which merchandise or services are sold.
        type: object
        properties:
          type:
            type: string
            default: Buyer
            enum:
            - Buyer
          id:
            example: did:web:waveridersupplies.example.com
            type: string
            format: uri
            description: A unique party identifier.
          name:
            example: Wave Rider Supplies, Inc
            type: string
            description: Trade party name.
          street:
            example: 210 Ocean Boulevard
            type: string
            description: The street component of the address.
          city:
            example: Los Angeles
            type: string
            description: The city component of the address.
          state:
            example: CA
            type: string
            description: The state component of the address.
          zip:
            example: 90001
            type: number
            description: Postal code.
          country:
            example: US
            type: string
            description: Country.
      notifyParty:
        description: Party to be notified of the arrival of goods.
        type: object
        properties:
          type:
            type: string
            default: NotifyParty
            enum:
            - NotifyParty
          id:
            example: did:web:waveridersupplies.example.com
            type: string
            format: uri
            description: A unique party identifier.
          name:
            example: Wave Rider Supplies, Inc
            type: string
            description: Trade party name.
          street:
            example: 210 Ocean Boulevard
            type: string
            description: The street component of the address.
          city:
            example: Los Angeles
            type: string
            description: The city component of the address.
          state:
            example: CA
            type: string
            description: The state component of the address.
          zip:
            example: 90001
            type: number
            description: Postal code.
          country:
            example: US
            type: string
            description: Country.
      insuredParty:
        description: Party which benefits from insurance coverage.
        type: object
        properties:
          type:
            type: string
            default: InsuredParty
            enum:
            - InsuredParty
          id:
            example: did:web:surfpro.example.com
            type: string
            format: uri
            description: A unique party identifier.
          name:
            example: SurfPro Manufacturing Inc.
            type: string
            description: Trade party name.
      placeOfDespatch:
        description: Place from or at which goods are despatched.
        type: object
        properties:
          name:
            example: Port of Brisbane
            type: string
            description: Location name.
          city:
            example: Brisbane
            type: string
            description: City.
          state:
            example: QLD
            type: string
            description: State.
          country:
            example: AU
            type: string
            description: Country.
          unlocode:
            example: https://service.unece.org/trade/locode/au.htm#AUBNE
            type: string
            format: uri
            description: UN/LOCODE identifier.
      placeOfIssue:
        description: Location where the document was issued.
        type: object
        properties:
          city:
            example: Gold Coast
            type: string
            description: City where issued.
          state:
            example: QLD
            type: string
            description: State where issued.
          country:
            example: AU
            type: string
            description: Country where issued.
      originCountry:
        description: Name of the country in which the goods have been produced or manufactured.
        type: object
        properties:
          country:
            example: AU
            type: string
            description: ISO country code.
          name:
            example: Australia
            type: string
            description: Country name.
      transportMeansIdentifier:
        example: MV Pacific Carrier
        type: string
        description: Name of a specific means of transport such as the vessel name.
      vehicleRegistrationNumber:
        example: IMO9876543
        type: string
        description: Identifier of a specific means of transport such as the IMO number of a vessel.
      numberOfPackages:
        example: 18
        type: number
        description: Total number of packages in the consignment.
      grossWeight:
        description: Total gross weight of the consignment including packaging.
        type: object
        properties:
          amount:
            example: 395.0
            type: number
            format: float
            description: Weight amount.
          unit:
            example: KGS
            type: string
            description: Weight unit.
      netWeight:
        description: Total net weight of the consignment excluding packaging.
        type: object
        properties:
          amount:
            example: 362.5
            type: number
            format: float
            description: Weight amount.
          unit:
            example: KGS
            type: string
            description: Weight unit.
      goods:
        description: 'Goods items covered by the letter of instructions'
        type: array
        items:
          type: object
          properties:
            description:
              example: Professional Longboard - Ocean Series, 9'6" length
              type: string
              description: Plain language description of the nature of a goods item.
            hsCode:
              example: "950630"
              type: string
              description: Code specifying a type of goods for Customs purposes.
            packagingType:
              example: CT
              type: string
              description: Code specifying the type of packaging of an item (UN/CEFACT rec 21).
            shippingMarks:
              example: "SURF-AU-001 / FRAGILE / THIS SIDE UP"
              type: string
              description: Free form description of the marks and numbers on a transport unit or package.
            quantity:
              description: Number of units.
              type: object
              properties:
                amount:
                  example: 25
                  type: number
                  description: Quantity amount.
                unit:
                  example: Units
                  type: string
                  description: Unit of measure.
            netWeight:
              description: Net weight of this goods item.
              type: object
              properties:
                amount:
                  example: 187.5
                  type: number
                  format: float
                  description: Weight amount.
                unit:
                  example: KGS
                  type: string
                  description: Weight unit.
            grossWeight:
              description: Gross weight of this goods item including packaging.
              type: object
              properties:
                amount:
                  example: 200.0
                  type: number
                  format: float
                  description: Weight amount.
                unit:
                  example: KGS
                  type: string
                  description: Weight unit.
            volume:
              description: Volume of this goods item.
              type: object
              properties:
                amount:
                  example: 1.8
                  type: number
                  format: float
                  description: Volume amount.
                unit:
                  example: MTQ
                  type: string
                  description: Volume unit.
            packageLength:
              description: Length of the package.
              type: object
              properties:
                amount:
                  example: 320
                  type: number
                  format: float
                  description: Length amount.
                unit:
                  example: CMT
                  type: string
                  description: Length unit.
            packageWidth:
              description: Width of the package.
              type: object
              properties:
                amount:
                  example: 60
                  type: number
                  format: float
                  description: Width amount.
                unit:
                  example: CMT
                  type: string
                  description: Width unit.
            value:
              description: Value of the goods item.
              type: object
              properties:
                amount:
                  example: 18750.00
                  type: number
                  format: float
                  description: Monetary amount.
                currency:
                  example: USD
                  type: string
                  description: Currency code.
          description: A specific goods item covered by the letter of instructions.
    required:
      - issueDate
      - despatchDate
      - incoterms
      - consignor
      - consignee
      - freightForwarder
      - placeOfDespatch
      - placeOfIssue
      - originCountry
      - numberOfPackages
      - grossWeight
      - netWeight
      - goods