@spec ensure_class(data(), String.t()) :: data()

Removes any existing class markers and sets the provided class on the payload.

@spec ensure_id(data(), opts()) :: data()

Ensures a UUID is present on the payload. By default a new UUID is generated using Uniq.UUID. Use auto_generate_id: false to skip automatic generation.

@spec ensure_id_value(data(), String.t()) :: data()

Removes any existing id markers and sets the provided id on the payload.

@spec normalize_keys(data()) :: data()

Normalizes a payload by converting atom keys to strings and recursively normalizing nested maps or lists.

Structs are passed through unchanged (they will be serialized later by serialize_properties/1).

@spec prepare_for_insert(data(), String.t(), opts()) :: data()

Prepares a payload for insertion by normalizing keys, generating an id when necessary, applying the collection class, handling vectors, and merging references.

Vector Support

Supports both single vector and named vectors (mutually exclusive):

• :vector - Single vector for the default vector
• :vectors - Map of named vectors (e.g., %{"title_vector" => [0.1, 0.2]})

Raises ArgumentError if both :vector and :vectors are provided.

Reference Support

Supports inline references via the :references key:

• Single UUID: %{"hasAuthor" => "uuid-123"}
• Multiple UUIDs: %{"hasAuthors" => ["uuid-1", "uuid-2"]}
• Multi-target: %{"relatedTo" => %{target_collection: "Category", uuids: "cat-uuid"}}

References are converted to beacon format and merged into properties.

Property Value Serialization

Special types are automatically serialized to Weaviate-compatible formats via the WeaviateEx.Types.Serializable protocol:

• DateTime - RFC3339 format (ISO8601 with timezone)
• NaiveDateTime - RFC3339 format (without timezone)
• Date - ISO8601 date at midnight UTC
• GeoCoordinate - %{"latitude" => lat, "longitude" => lon}
• PhoneNumber - %{"input" => number, "defaultCountry" => country}
• Blob - Base64-encoded string

Nested objects and arrays are recursively serialized.

@spec prepare_for_patch(data()) :: data()

Normalizes a payload for patch operations (class/id handled by the server).

@spec prepare_for_update(data(), String.t(), String.t(), opts()) :: data()

Prepares a payload for update requests by normalizing keys, forcing the id, applying the collection class, and handling vectors.

Vector Support

Supports both single vector and named vectors (mutually exclusive):

• :vector - Single vector for the default vector
• :vectors - Map of named vectors (e.g., %{"title_vector" => [0.1, 0.2]})

Raises ArgumentError if both :vector and :vectors are provided.