{"id":2882,"library":"azure-schemaregistry","title":"Azure Schema Registry Client Library","description":"The Azure Schema Registry client library for Python (version 1.3.0) provides a robust interface for interacting with the Azure Schema Registry service. This service, hosted by Azure Event Hubs, offers a centralized repository for managing, versioning, and storing schemas. The library enables applications to register and retrieve schemas, and includes a JSON schema-based encoder for efficient payload encoding and decoding using schema identifiers rather than full schema definitions. It adheres to the Azure SDK guidelines, offering a consistent and Pythonic experience. It is actively maintained with a regular release cadence as part of the broader Azure SDK for Python.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python","tags":["Azure","Schema Registry","Event Hubs","messaging","schema validation","JSON schema","cloud"],"install":[{"cmd":"pip install azure-schemaregistry","lang":"bash","label":"Base installation"},{"cmd":"pip install azure-schemaregistry[jsonencoder]","lang":"bash","label":"With JSON schema validation support"}],"dependencies":[{"reason":"Required for Azure Active Directory authentication with DefaultAzureCredential.","package":"azure-identity","optional":false},{"reason":"Core shared components for Azure client libraries; minimum version 1.28.0 required for 1.3.0.","package":"azure-core","optional":false},{"reason":"Required for JSON schema validation if using the `jsonencoder` extra.","package":"jsonschema","optional":true},{"reason":"Required for integration with azure.eventhub.EventData.","package":"azure-eventhub>=5.9.0","optional":true}],"imports":[{"symbol":"SchemaRegistryClient","correct":"from azure.schemaregistry import SchemaRegistryClient"},{"note":"The JsonSchemaEncoder is nested under 'encoder.jsonencoder' for version 1.3.0 and later.","wrong":"from azure.schemaregistry.encoder import JsonSchemaEncoder","symbol":"JsonSchemaEncoder","correct":"from azure.schemaregistry.encoder.jsonencoder import JsonSchemaEncoder"},{"note":"Required for authenticating with Azure services. Part of the 'azure-identity' package.","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"}],"quickstart":{"code":"import os\nfrom azure.schemaregistry import SchemaRegistryClient\nfrom azure.identity import DefaultAzureCredential\n\n# Set environment variables for authentication and Schema Registry endpoint\n# AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET for DefaultAzureCredential\n# SCHEMAREGISTRY_FULLY_QUALIFIED_NAMESPACE for the Schema Registry endpoint\n\nfully_qualified_namespace = os.environ.get('SCHEMAREGISTRY_FULLY_QUALIFIED_NAMESPACE', 'your-namespace.servicebus.windows.net')\nschema_group = os.environ.get('SCHEMAREGISTRY_GROUP_NAME', 'my-schema-group')\nschema_name = os.environ.get('SCHEMAREGISTRY_SCHEMA_NAME', 'my-json-schema')\nschema_definition = '''{\n    \"type\": \"object\",\n    \"$id\": \"https://example.com/example.json\",\n    \"title\": \"Person\",\n    \"description\": \"A person schema\",\n    \"properties\": {\n        \"name\": {\n            \"type\": \"string\",\n            \"description\": \"The person's name.\"\n        },\n        \"age\": {\n            \"type\": \"integer\",\n            \"description\": \"The person's age.\",\n            \"minimum\": 0\n        }\n    },\n    \"required\": [\"name\"]\n}'''\nschema_format = \"Json\"\n\ncredential = DefaultAzureCredential()\nclient = SchemaRegistryClient(fully_qualified_namespace, credential)\n\ntry:\n    # Register a schema\n    schema_properties = client.register_schema(\n        group_name=schema_group,\n        name=schema_name,\n        format=schema_format,\n        definition=schema_definition\n    )\n    print(f\"Registered schema with ID: {schema_properties.id}\")\n    print(f\"Schema Version: {schema_properties.version}\")\n\n    # Get a schema by its ID\n    retrieved_schema = client.get_schema(schema_properties.id)\n    print(f\"Retrieved schema name: {retrieved_schema.name}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Always close the credential when done (if using certain types like ManagedIdentityCredential)\n    # DefaultAzureCredential handles this contextually.\n    pass","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or later.","message":"Python 3.7 is no longer supported with `azure-schemaregistry` version 1.3.0 and later. Python 3.8 or higher is now required.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Update method and parameter names according to the current API reference. Refer to the Changelog for specific version details.","message":"Several 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`).","severity":"breaking","affected_versions":">=1.0.0, <1.3.0 (changes landed in various 1.x.x releases leading to 1.3.0)"},{"fix":"Ensure the namespace string strictly follows the format: `your-eventhub-namespace.servicebus.windows.net`.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `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').","message":"Authentication 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Validate your input content against the registered schema and ensure the `content_type` header is correctly formatted, especially the embedded schema ID.","message":"When 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>`.","severity":"gotcha","affected_versions":">=1.3.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}