"$schema": https://json-schema.org/draft/2020-12/schema
title: Customs Declaration
description: A formal document submitted to customs authorities declaring the details of goods being imported or exported, including their nature, value, and origin for duty assessment and regulatory compliance.
type: object
required:
  - "@context"
  - type
  - credentialSchema
  - validTo
  - issuer
  - credentialSubject
properties:
  "@context":
    type: string
    format: uri
    description: 'Linked Data context for semantic interoperability'
    const: "https://unvtd.unece.org/customs-declaration-context.json"
  type:
    type: array
    description: 'Document types'
    items:
      type: string
      enum:
        - VerifiableCredential
        - CustomsDeclaration
    minItems: 2
    maxItems: 2
    example:
      - VerifiableCredential
      - CustomsDeclaration
  credentialSchema:
    type: object
    description: 'Reference to the credential schema for validation'
    properties:
      id:
        type: string
        format: uri
        const: "https://unvtd.unece.org/customs-declaration-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:cd-2025-au-export-001"
  validFrom:
    example: 2025-03-09:10:00
    type: string
    format: date-time
    description: 'Credential validity start date'
  validTo:
    example: 2026-03-09:10:00
    type: string
    format: date-time
    description: 'Credential validity end date'
  issuer:
    name: 'Issuer'
    description: 'Identifier of the customs administration responsible for the declaration (e.g., DID)'
    type: string
    format: uri
    example: did:web:customs.example.gov
  credentialSubject:
    name: CustomsDeclaration
    description: 'Customs declaration details'
    type: object
    properties:
      declarationNumber:
        example: EXP-2025-AU-123456
        type: string
        description: Reference number, assigned or accepted by Customs, to identify a goods declaration.
      traderAssignedReference:
        example: SURFPRO-EXP-2025-001
        type: string
        description: Reference assigned by a trader to identify a declaration.
      issueDate:
        example: '2025-03-09T00:00:00Z'
        type: string
        format: date-time
        description: Date that a document was issued.
      exporter:
        description: Party who makes, or on whose behalf the export declaration is made.
        type: object
        properties:
          type:
            type: string
            default: Exporter
            enum:
            - Exporter
          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.
          eoriNumber:
            example: AU1234567890
            type: string
            description: Economic Operators Registration and Identification number.
      importer:
        description: Party who makes - or on whose behalf a Customs clearing agent makes - an import declaration.
        type: object
        properties:
          type:
            type: string
            default: Importer
            enum:
            - Importer
          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 Road
            type: string
            description: The street component of the address
          city:
            example: Williamsburg
            type: string
            description: The city component of the address
          state:
            example: NSW
            type: string
            description: The state component of the address
          zip:
            example: 75002
            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 Road
            type: string
            description: The street component of the address
          city:
            example: Williamsburg
            type: string
            description: The city component of the address
          state:
            example: NSW
            type: string
            description: The state component of the address
          zip:
            example: 75002
            type: number
            description: 'Postal code'
          country:
            example: AU
            type: string
            description: Country.
      carrier:
        description: Party providing the transport of goods between named points.
        type: object
        properties:
          type:
            type: string
            default: Carrier
            enum:
            - Carrier
          id:
            example: did:web:pacificshipping.example.com
            type: string
            format: uri
            description: A unique party identifier.
          name:
            example: Pacific Ocean Shipping Lines
            type: string
            description: Trade party name.
          street:
            example: 88 Harbour Street
            type: string
            description: The street component of the address
          city:
            example: Sydney
            type: string
            description: The city component of the address
          state:
            example: NSW
            type: string
            description: The state component of the address
          zip:
            example: 2000
            type: number
            description: 'Postal code'
          country:
            example: AU
            type: string
            description: Country.
      exportationCountry:
        description: Country from which goods are exported.
        type: object
        properties:
          country:
            example: AU
            type: string
            description: ISO country code
          name:
            example: Australia
            type: string
            description: Country name
      destinationCountry:
        description: Country to which goods are destined.
        type: object
        properties:
          country:
            example: AU
            type: string
            description: ISO country code
          name:
            example: Australia
            type: string
            description: Country name
      consignmentDestinationCountry:
        description: Name of the country to which the goods are to be delivered.
        type: object
        properties:
          country:
            example: AU
            type: string
            description: ISO country code
          name:
            example: Australia
            type: string
            description: Country name
      exitCustomsOffice:
        description: Customs office at which the goods leave the customs territory.
        type: object
        properties:
          code:
            example: AUGOL
            type: string
            description: Office code
          name:
            example: Gold Coast Customs Office
            type: string
            description: Office name
          location:
            example: Gold Coast Airport
            type: string
            description: Office location
      entryCustomsOffice:
        description: Customs office at which the goods enter the customs territory.
        type: object
        properties:
          code:
            example: AUSYD
            type: string
            description: Office code
          name:
            example: Sydney Customs Office
            type: string
            description: Office name
          location:
            example: Sydney International Airport
            type: string
            description: Office location
      transportContractNumber:
        example: BKG123456789
        type: string
        description: Reference number to identify a document evidencing a transport contract.
      invoiceNumber:
        example: INV-2025-031-001
        type: string
        description: Reference number to identify an invoice.
      invoiceDate:
        example: '2025-03-10T00:00:00Z'
        type: string
        format: date-time
        description: Date of issue of an invoice.
      tradeTermsConditionsCode:
        example: FOB
        type: string
        description: Code specifying the delivery or transport terms (Incoterms).
      tradeTermsConditionsDescription:
        example: FOB Port of Gold Coast
        type: string
        description: Free form description of delivery or transport terms.
      paymentMethod:
        example: Wire Transfer
        type: string
        description: Code specifying a method of payment.
      modeOfTransport:
        example: "1"
        type: string
        description: Code specifying a mode of transport (1=Maritime, 3=Road, 4=Air, etc.).
      transportMeansIdentifier:
        example: PACIFIC VOYAGER
        type: string
        description: Name of a specific means of transport such as the vessel name.
      transportMeansRegistration:
        example: IMO9876543
        type: string
        description: Identifier of a specific means of transport.
      transportMeansAtBorder:
        example: PACIFIC VOYAGER
        type: string
        description: Identifier of the means of transport used in crossing the border.
      natureOfTransaction:
        example: Sale
        type: string
        description: Textual representation of a type of contract.
      declarationGoods:
        name: Declaration Goods
        description: 'Goods declared to customs'
        type: array
        items:
          type: object
          properties:
            sequenceIdentifier:
              example: 1
              type: number
              description: Sequence number differentiating a specific goods item.
            description:
              example: Professional Longboard - Ocean Series, 9'6" length
              type: string
              description: Plain language description of the goods.
            hsCode:
              example: "950630"
              type: string
              description: Code specifying a type of goods for Customs purposes.
            originCountry:
              example: AU
              type: string
              description: Country where the goods were produced or manufactured.
            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: Total net weight of the goods.
              type: object
              properties:
                amount:
                  example: 187.5
                  type: number
                  format: float
                  description: 'Weight amount'
                unit:
                  example: KGS
                  type: string
                  description: 'Weight unit'
            grossWeight:
              description: Total gross weight including packaging.
              type: object
              properties:
                amount:
                  example: 200.0
                  type: number
                  format: float
                  description: 'Weight amount'
                unit:
                  example: KGS
                  type: string
                  description: 'Weight unit'
            numberOfPackages:
              example: 5
              type: number
              description: Number of packages per goods item.
            packagingType:
              example: CT
              type: string
              description: Code specifying the type of packaging (CT=Carton, etc.).
            shippingMarks:
              example: "SURFPRO/WRS/001-005"
              type: string
              description: Free form description of the marks and numbers on packages.
            customsValue:
              description: 'Value declared for customs purposes'
              type: object
              properties:
                amount:
                  example: 18750.00
                  type: number
                  format: float
                  description: 'Monetary amount'
                currency:
                  example: USD
                  type: string
                  description: 'Currency code'
            statisticalValue:
              description: 'Value declared for statistical purposes'
              type: object
              properties:
                amount:
                  example: 18750.00
                  type: number
                  format: float
                  description: 'Monetary amount'
                currency:
                  example: USD
                  type: string
                  description: 'Currency code'
            taxRegimeType:
              example: STANDARD
              type: string
              description: Code specifying a regime according to which tax is assessed.
          description: A specific goods item in the declaration.
      totalInvoiceAmount:
        description: Total monetary amount charged.
        type: object
        properties:
          amount:
            example: 73250.00
            type: number
            format: float
            description: 'Monetary amount'
          currency:
            example: USD
            type: string
            description: 'Currency code'
      totalGrossWeight:
        description: Total gross weight of all goods.
        type: object
        properties:
          amount:
            example: 520.0
            type: number
            format: float
            description: 'Weight amount'
          unit:
            example: KGS
            type: string
            description: 'Weight unit'
      totalNetWeight:
        description: Total net weight of all goods.
        type: object
        properties:
          amount:
            example: 475.0
            type: number
            format: float
            description: 'Weight amount'
          unit:
            example: KGS
            type: string
            description: 'Weight unit'
      totalNumberOfPackages:
        example: 18
        type: number
        description: Total number of packages.
      ucr:
        example: AU2025SURF001234
        type: string
        description: Unique Consignment Reference identifying a particular consignment.
    required:
      - declarationNumber
      - issueDate
      - exporter
      - declarationGoods