Install & Compatibility
Where this runs
tested against v1.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.419s · 27.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.9s · import 0.389s · 27MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SchemaRegistryClient
✓ from azure.schemaregistry import SchemaRegistryClient
JsonSchemaEncoder
✓ from azure.schemaregistry.encoder.jsonencoder import JsonSchemaEncoder
✗ from azure.schemaregistry.encoder import JsonSchemaEncoder
The JsonSchemaEncoder is nested under 'encoder.jsonencoder' for version 1.3.0 and later.
DefaultAzureCredential
✓ from azure.identity import DefaultAzureCredential
Required for authenticating with Azure services. Part of the 'azure-identity' package.
This quickstart demonstrates how to instantiate a `SchemaRegistryClient` using `DefaultAzureCredential` and then register and retrieve a JSON schema. Ensure that `SCHEMAREGISTRY_FULLY_QUALIFIED_NAMESPACE`, `SCHEMAREGISTRY_GROUP_NAME`, and `SCHEMAREGISTRY_SCHEMA_NAME` environment variables are set, along with Azure AD credentials (`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`) for `DefaultAzureCredential` to function.
import os
from azure.schemaregistry import SchemaRegistryClient
from azure.identity import DefaultAzureCredential
# Set environment variables for authentication and Schema Registry endpoint
# AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET for DefaultAzureCredential
# SCHEMAREGISTRY_FULLY_QUALIFIED_NAMESPACE for the Schema Registry endpoint
fully_qualified_namespace = os.environ.get('SCHEMAREGISTRY_FULLY_QUALIFIED_NAMESPACE', 'your-namespace.servicebus.windows.net')
schema_group = os.environ.get('SCHEMAREGISTRY_GROUP_NAME', 'my-schema-group')
schema_name = os.environ.get('SCHEMAREGISTRY_SCHEMA_NAME', 'my-json-schema')
schema_definition = '''{
"type": "object",
"$id": "https://example.com/example.json",
"title": "Person",
"description": "A person schema",
"properties": {
"name": {
"type": "string",
"description": "The person's name."
},
"age": {
"type": "integer",
"description": "The person's age.",
"minimum": 0
}
},
"required": ["name"]
}'''
schema_format = "Json"
credential = DefaultAzureCredential()
client = SchemaRegistryClient(fully_qualified_namespace, credential)
try:
# Register a schema
schema_properties = client.register_schema(
group_name=schema_group,
name=schema_name,
format=schema_format,
definition=schema_definition
)
print(f"Registered schema with ID: {schema_properties.id}")
print(f"Schema Version: {schema_properties.version}")
# Get a schema by its ID
retrieved_schema = client.get_schema(schema_properties.id)
print(f"Retrieved schema name: {retrieved_schema.name}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Always close the credential when done (if using certain types like ManagedIdentityCredential)
# DefaultAzureCredential handles this contextually.
pass
Debug
Known issues
breakingPython 3.7 is no longer supported with `azure-schemaregistry` version 1.3.0 and later. Python 3.8 or higher is now required.fixUpgrade your Python environment to 3.8 or later.
affects: >=1.3.0
breakingSeveral API methods and parameters were renamed or reordered in earlier stable releases. Specifically, `get_schema_id` was renamed to `get_schema_properties`, the `schema_id` parameter in `get_schema` was renamed to `id`, and the `register_schema` and `get_schema_properties` methods had parameter reordering and renaming (`schema_group` to `group_name`, `schema_name` to `name`).fixUpdate method and parameter names according to the current API reference. Refer to the Changelog for specific version details.
affects: >=1.0.0, <1.3.0 (changes landed in various 1.x.x releases leading to 1.3.0)
gotchaThe `fully_qualified_namespace` for the `SchemaRegistryClient` must be in the format `<yournamespace>.servicebus.windows.net/`. Incorrect formats (e.g., including `sb://`) will lead to connection errors or 'Bad Request' responses.fixEnsure the namespace string strictly follows the format: `your-eventhub-namespace.servicebus.windows.net`.
affects: All versions
gotchaAuthentication requires the `azure-identity` package and proper Azure Active Directory (AAD) setup. If `DefaultAzureCredential` fails, verify your environment variables (`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`) or Managed Identity configuration. Role-Based Access Control (RBAC) permissions on the Schema Registry are crucial.fixInstall `azure-identity` (`pip install azure-identity`), configure appropriate environment variables or managed identity, and ensure your AAD principal has necessary permissions (e.g., 'Schema Registry Contributor' or 'Schema Registry Reader').
affects: All versions
gotchaWhen using `JsonSchemaEncoder`, encoding/decoding errors (e.g., invalid content or content type) will raise `azure.schemaregistry.encoder.jsonencoder.InvalidContentError`. The `content_type` must adhere to the format `application/json;serialization=Json+<schema ID>`.fixValidate your input content against the registered schema and ensure the `content_type` header is correctly formatted, especially the embedded schema ID.
affects: >=1.3.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.identity'
The `azure-identity` package, which is required for authenticating with Azure services like Schema Registry, is not installed in your Python environment.
fixInstall the `azure-identity` package using pip: `pip install azure-identity`
azure.core.exceptions.ServiceRequestError: <urllib3.connection.HTTPSConnection object at ...>: Failed to establish a new connection: [Errno 11001] getaddrinfo failed
The fully qualified namespace provided for the Schema Registry client is incorrect or cannot be resolved via DNS, leading to a network connection failure.
fixEnsure the `fully_qualified_namespace` is in the correct format, typically `<your-eventhub-namespace>.servicebus.windows.net`, and accessible from your network. Do not include `sb://` or `Endpoint=` prefixes from connection strings.
azure.schemaregistry.encoder.jsonencoder.InvalidContentError
This error occurs when the content being encoded does not conform to the associated JSON schema, or during decoding, if the `content_type` header is malformed or the payload doesn't match the retrieved schema.
fixVerify that the data you are trying to encode strictly adheres to the JSON schema definition. When decoding, ensure the incoming message's `content_type` includes a valid schema ID and that the payload is correctly formatted according to the schema.
Json schema validation failed: An item with the same key has already been added
This error, often returned by the Schema Registry service, indicates that the submitted JSON schema definition contains duplicate field names, particularly common within union types or nested record definitions.
fixReview and modify your JSON schema definition to ensure all field names, especially within complex types like unions, are unique to prevent naming conflicts.
Upgrade
Version history
1.3.0latest on PyPI · released Sep 18, 2024
Audit
Dependencies
azure-identityrequiredRequired for Azure Active Directory authentication with DefaultAzureCredential.
azure-corerequiredCore shared components for Azure client libraries; minimum version 1.28.0 required for 1.3.0.
jsonschemaoptionalRequired for JSON schema validation if using the `jsonencoder` extra.
azure-eventhub>=5.9.0optionalRequired for integration with azure.eventhub.EventData.