{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openfreytprotocol.example/schemas/v0/execution-handover",
  "title": "ExecutionHandover",
  "description": "A disclosure-controlled operational package containing only the stops, time windows, cargo facts, equipment constraints, references, instructions, documents and contact details required to execute the committed movement. The source and executing systems retain their own local records; the handover links them through the commitment identifier and namespaced external references.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUIDv7 resource identifier."
    },
    "resourceVersion": {
      "type": "integer",
      "minimum": 1,
      "description": "Optimistic-concurrency counter. Handovers are create-once and immutable; this remains 1 for the life of the resource."
    },
    "ownerOrganizationId": {
      "type": "string",
      "description": "Opaque broker-scoped identifier of the organization that owns this resource."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 / RFC 3339 timestamp when the resource was first created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 / RFC 3339 timestamp of the most recent mutation. Equal to createdAt for this create-once resource."
    },
    "externalReferences": {
      "type": "array",
      "items": { "$ref": "#/$defs/ExternalReference" },
      "description": "Namespaced references to records in external systems (TMS, ERP, etc.)."
    },
    "commitmentId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the TransportCommitment this handover executes."
    },
    "sourceOrganizationId": {
      "type": "string",
      "minLength": 1,
      "description": "Organization delivering the operational package."
    },
    "executingOrganizationId": {
      "type": "string",
      "minLength": 1,
      "description": "Organization expected to import or link the operational package into its own systems."
    },
    "stops": {
      "type": "array",
      "description": "Disclosure-controlled ordered stop facts required to execute the movement.",
      "items": { "type": "object" }
    },
    "timeWindows": {
      "type": "object",
      "description": "Pickup and delivery window facts disclosed for execution.",
      "properties": {
        "pickupWindowStart": { "type": "string", "format": "date-time" },
        "pickupWindowEnd": { "type": "string", "format": "date-time" },
        "deliveryWindowStart": { "type": "string", "format": "date-time" },
        "deliveryWindowEnd": { "type": "string", "format": "date-time" }
      }
    },
    "cargoFacts": {
      "type": "object",
      "description": "Disclosure-controlled cargo facts required to execute the movement (weight, volume, goods profile, hazard class, etc.)."
    },
    "equipmentConstraints": {
      "type": "object",
      "description": "Vehicle/equipment constraints required to execute the movement."
    },
    "references": {
      "type": "array",
      "items": { "$ref": "#/$defs/ExternalReference" },
      "description": "Additional namespaced references relevant to execution (e.g. booking numbers, order numbers)."
    },
    "instructions": {
      "type": "string",
      "description": "Free-text operational instructions required to execute the movement."
    },
    "documents": {
      "type": "array",
      "description": "References to documents required for execution (e.g. delivery notes, customs paperwork).",
      "items": { "type": "object" }
    },
    "contactDetails": {
      "type": "object",
      "description": "Disclosure-controlled operational contact details required for execution."
    },
    "deliveryAttemptCount": {
      "type": "integer",
      "minimum": 1,
      "description": "Count of delivery attempts made for this handover; used together with commitmentId for duplicate-delivery detection."
    },
    "dedupKey": {
      "type": "string",
      "minLength": 1,
      "description": "Stable natural key used to detect duplicate delivery of the same handover. Defaults to commitmentId when not otherwise specified."
    }
  },
  "required": [
    "id",
    "resourceVersion",
    "ownerOrganizationId",
    "createdAt",
    "updatedAt",
    "commitmentId",
    "sourceOrganizationId",
    "executingOrganizationId"
  ],
  "$defs": {
    "ExternalReference": {
      "type": "object",
      "properties": {
        "system": { "type": "string" },
        "type": { "type": "string" },
        "value": { "type": "string" }
      },
      "required": ["system", "type", "value"]
    }
  }
}