Airbyte Protocol Models (Pydantic v2)

0.19.0 verified Fri May 15 auth: no python

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.

pip install airbyte-protocol-models-pdv2

Common errors

error ImportError: cannot import name 'AirbyteMessage' from 'airbyte_protocol_models_pdv2' ↓

cause The 'AirbyteMessage' class is not present in the 'airbyte_protocol_models_pdv2' package.

fix

Use 'from airbyte_cdk.models import AirbyteMessage' instead.

error ModuleNotFoundError: No module named 'airbyte_protocol_models_pdv2' ↓

cause The 'airbyte_protocol_models_pdv2' package is not installed in the Python environment.

fix

Install the package using 'pip install airbyte-protocol-models-pdv2'.

error AttributeError: module 'airbyte_protocol_models_pdv2' has no attribute 'AirbyteMessage' ↓

cause The 'AirbyteMessage' class is not defined in the 'airbyte_protocol_models_pdv2' module.

fix

Import 'AirbyteMessage' from 'airbyte_cdk.models' instead.

error AttributeError: 'AirbyteStream' object has no attribute 'schema' ↓

cause The field 'schema' in Airbyte protocol models was renamed to 'json_schema' to better align with JSON Schema specifications and avoid ambiguity.

fix

Update your code to use 'json_schema' instead of 'schema' when accessing or manipulating the schema field of Airbyte protocol models.

# Old code
# stream.schema

# New code
stream.json_schema

error ImportError: cannot import name 'AdvancedAuth' from 'airbyte_cdk.models.airbyte_protocol' ↓

cause This error typically occurs when attempting to import a model or class that has been removed, renamed, or moved to a different module in a newer version of the Airbyte Protocol or `airbyte-cdk`. For example, `AdvancedAuth` was moved or deprecated.

fix

Review the airbyte-protocol-models-pdv2 documentation or changelog for the specific version you are using to find the correct import path or the equivalent new model/class. You might need to update your connector code to align with the latest protocol definitions.

# Example of a common import pattern for core models
from airbyte_protocol_models_pdv2.airbyte_protocol import AirbyteMessage, AirbyteRecordMessage, Type

Warnings

breaking 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. ↓

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.

breaking 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. ↓

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.

breaking The field 'schema' was renamed to 'json_schema' in the protocol models. ↓

fix If you were directly accessing or manipulating a 'schema' field on any protocol model, update your code to use 'json_schema' instead.

gotcha The Airbyte Protocol is versioned independently of the main Airbyte Platform. This means that upgrading one does not automatically guarantee compatibility with the other. ↓

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.

Install compatibility last tested: 2026-05-15 v0.18.0 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - - 27.9M - broken

3.10 slim (glibc) wheel 3.7s - 28M - broken

3.11 alpine (musl) wheel - - 30.6M - broken

3.11 slim (glibc) wheel 3.0s - 30M - broken

3.12 alpine (musl) wheel - - 22.3M - broken

3.12 slim (glibc) wheel 2.5s - 22M - broken

3.13 alpine (musl) wheel - - 22.0M - broken

3.13 slim (glibc) wheel 2.6s - 22M - broken

3.9 alpine (musl) wheel - - 27.4M - broken

3.9 slim (glibc) wheel 4.2s - 27M - broken

Imports

AirbyteMessage
wrong
```
from airbyte_protocol_models.airbyte_protocol import AirbyteMessage
```
correct
```
from airbyte_protocol_models_pdv2.airbyte_protocol import AirbyteMessage
```
The `-pdv2` suffix indicates the Pydantic v2 version. Do not confuse it with `airbyte-protocol-models` which uses Pydantic v1.

AirbyteRecordMessage

from airbyte_protocol_models_pdv2.airbyte_protocol import AirbyteRecordMessage

Type
```
from airbyte_protocol_models_pdv2.airbyte_protocol import Type
```
Refers to the Airbyte message `Type` enum (e.g., RECORD, STATE, LOG).

Quickstart

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.

import json
from airbyte_protocol_models_pdv2.airbyte_protocol import AirbyteMessage, AirbyteRecordMessage, Type

# Create a sample record message
record_data = {"id": 1, "name": "Alice", "age": 30}
record_message = AirbyteRecordMessage(
    stream="users",
    data=record_data,
    emitted_at=1678886400000 # Unix timestamp in milliseconds
)

# Wrap it in an AirbyteMessage envelope
airbyte_message = AirbyteMessage(
    type=Type.RECORD,
    record=record_message
)

# Serialize the message to JSON (as expected by the Airbyte Protocol)
json_output = airbyte_message.model_dump_json(by_alias=True)
print("Serialized JSON message:")
print(json_output)

# Deserialize the JSON back into an AirbyteMessage object
deserialized_message = AirbyteMessage.model_validate_json(json_output)
print("\nDeserialized message type:", deserialized_message.type)
if deserialized_message.record:
    print("Deserialized record data:", deserialized_message.record.data)