{"id":4415,"library":"airbyte-protocol-models-pdv2","title":"Airbyte Protocol Models (Pydantic v2)","description":"This library provides Pydantic v2 models that declare the Airbyte Protocol. It defines the structured messages (like records, states, logs, and catalogs) used for inter-process communication between Airbyte sources, destinations, and the platform. It is currently at version 0.19.0 and receives frequent updates, often adding new features and protocol extensions.","status":"active","version":"0.19.0","language":"en","source_language":"en","source_url":"https://github.com/airbytehq/airbyte-protocol","tags":["airbyte","etl","data-integration","pydantic","data-protocol","data-modeling"],"install":[{"cmd":"pip install airbyte-protocol-models-pdv2","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"The package is explicitly built on Pydantic v2 models, which is a core dependency for data validation and serialization.","package":"pydantic>=2"}],"imports":[{"note":"The `-pdv2` suffix indicates the Pydantic v2 version. Do not confuse it with `airbyte-protocol-models` which uses Pydantic v1.","wrong":"from airbyte_protocol_models.airbyte_protocol import AirbyteMessage","symbol":"AirbyteMessage","correct":"from airbyte_protocol_models_pdv2.airbyte_protocol import AirbyteMessage"},{"symbol":"AirbyteRecordMessage","correct":"from airbyte_protocol_models_pdv2.airbyte_protocol import AirbyteRecordMessage"},{"note":"Refers to the Airbyte message `Type` enum (e.g., RECORD, STATE, LOG).","symbol":"Type","correct":"from airbyte_protocol_models_pdv2.airbyte_protocol import Type"}],"quickstart":{"code":"import json\nfrom airbyte_protocol_models_pdv2.airbyte_protocol import AirbyteMessage, AirbyteRecordMessage, Type\n\n# Create a sample record message\nrecord_data = {\"id\": 1, \"name\": \"Alice\", \"age\": 30}\nrecord_message = AirbyteRecordMessage(\n    stream=\"users\",\n    data=record_data,\n    emitted_at=1678886400000 # Unix timestamp in milliseconds\n)\n\n# Wrap it in an AirbyteMessage envelope\nairbyte_message = AirbyteMessage(\n    type=Type.RECORD,\n    record=record_message\n)\n\n# Serialize the message to JSON (as expected by the Airbyte Protocol)\njson_output = airbyte_message.model_dump_json(by_alias=True)\nprint(\"Serialized JSON message:\")\nprint(json_output)\n\n# Deserialize the JSON back into an AirbyteMessage object\ndeserialized_message = AirbyteMessage.model_validate_json(json_output)\nprint(\"\\nDeserialized message type:\", deserialized_message.type)\nif deserialized_message.record:\n    print(\"Deserialized record data:\", deserialized_message.record.data)","lang":"python","description":"This quickstart demonstrates how to create an `AirbyteRecordMessage`, wrap it within an `AirbyteMessage` envelope, serialize it to a JSON string, and then deserialize it back into a Pydantic object. This is fundamental for interacting with the Airbyte Protocol, where all messages are exchanged as JSON."},"warnings":[{"fix":"Ensure your entire project ecosystem is compatible with Pydantic v2. Migrate any existing Pydantic v1 models to v2, or isolate the use of this library in environments where Pydantic v1 is not present.","message":"This library (`-pdv2`) is built exclusively on Pydantic v2. If your project or other dependencies use Pydantic v1, mixing these models can lead to runtime errors or unexpected behavior due to API changes and incompatibility between Pydantic versions.","severity":"breaking","affected_versions":"All versions"},{"fix":"Update your code to use the latest protocol models, which are implicitly v0 (or the current major version of the protocol), and avoid any references to explicitly named V1 models.","message":"Protocol v1 models have been removed. Versions v0.17.0, v0.14.5, and v0.14.4 explicitly include changes to remove or move V1 models.","severity":"breaking","affected_versions":">=0.14.4"},{"fix":"If you were directly accessing or manipulating a 'schema' field on any protocol model, update your code to use 'json_schema' instead.","message":"The field 'schema' was renamed to 'json_schema' in the protocol models.","severity":"breaking","affected_versions":">=0.16.0"},{"fix":"Always check the compatibility matrix between your Airbyte Platform version and the Airbyte Protocol version (implied by the `airbyte-protocol-models-pdv2` library version) to avoid unexpected issues. Airbyte's pre-upgrade checks are designed to help, but awareness is key.","message":"The Airbyte Protocol is versioned independently of the main Airbyte Platform. This means that upgrading one does not automatically guarantee compatibility with the other.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}