{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openfreytprotocol.example/schemas/v0/handover-acknowledgement",
  "title": "HandoverAcknowledgement",
  "description": "Records whether the executing connector imported, linked, rejected or quarantined an ExecutionHandover. Successful acknowledgements include the destination external reference. Duplicate delivery must resolve to the same local record and acknowledgement. Commercial acceptance (TransportCommitment) and technical handover acknowledgement are separate transitions.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUIDv7 resource identifier."
    },
    "resourceVersion": {
      "type": "integer",
      "minimum": 1,
      "description": "Optimistic-concurrency counter. Acknowledgements 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.)."
    },
    "handoverId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the ExecutionHandover being acknowledged."
    },
    "acknowledgementStatus": {
      "type": "string",
      "enum": ["imported", "linked", "rejected", "quarantined"],
      "description": "Outcome of the executing connector's attempt to process the handover."
    },
    "destinationExternalReference": {
      "type": "string",
      "minLength": 1,
      "description": "Reference to the local record created or linked in the destination system. Required when acknowledgementStatus is 'imported' or 'linked'."
    },
    "acknowledgedByOrganizationId": {
      "type": "string",
      "minLength": 1,
      "description": "Organization that recorded this acknowledgement."
    },
    "acknowledgedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp at which the acknowledgement was recorded."
    },
    "rejectionReason": {
      "type": "string",
      "minLength": 1,
      "description": "Reason the handover could not be imported or linked. Required when acknowledgementStatus is 'rejected' or 'quarantined'."
    }
  },
  "required": [
    "id",
    "resourceVersion",
    "ownerOrganizationId",
    "createdAt",
    "updatedAt",
    "handoverId",
    "acknowledgementStatus",
    "acknowledgedByOrganizationId",
    "acknowledgedAt"
  ],
  "allOf": [
    {
      "if": {
        "properties": { "acknowledgementStatus": { "enum": ["imported", "linked"] } },
        "required": ["acknowledgementStatus"]
      },
      "then": { "required": ["destinationExternalReference"] }
    },
    {
      "if": {
        "properties": { "acknowledgementStatus": { "enum": ["rejected", "quarantined"] } },
        "required": ["acknowledgementStatus"]
      },
      "then": { "required": ["rejectionReason"] }
    }
  ],
  "$defs": {
    "ExternalReference": {
      "type": "object",
      "properties": {
        "system": { "type": "string" },
        "type": { "type": "string" },
        "value": { "type": "string" }
      },
      "required": ["system", "type", "value"]
    }
  }
}