Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Bug: Declarative component schema should validate inline stream schemas against JSON Schema spec

Open
  • Is something wrong?
#832 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
developer-experience, tooling

Research direction

Start with airbyte_cdk.sources.declarative.declarative_component_schema.yaml and inspect the InlineSchemaLoader.schema definition and manifest validation path. Exercise validation with the three invalid inline-schema examples in the issue; done means malformed schemas fail during manifest validation with clear errors rather than later Python runtime failures.

Written by the indexing model from the issue text.

Description

Workaround in MCP:

Current Behavior

The InlineSchemaLoader.schema field in declarative_component_schema.yaml is currently defined as:

schema:
  type: object
  additionalProperties: true

This allows any object, including invalid JSON schemas. For example, these invalid schemas currently pass validation:

Example 1: Invalid type value

schema:
  type: object
  properties:
    id:
      type: not_a_valid_type  # Should fail but doesn't

Example 2: Malformed structure
schema: "string instead of object" # Causes Python error later

Example 3: Invalid property definitions

schema:
  type: object
  properties:
    field: "should be object with type"  # Invalid structure

Problem

Invalid schemas pass manifest validation but cause issues later:

  1. Cryptic Python errors during stream reading - e.g., 'str' object has no attribute 'get' when schema is a string
  2. Runtime failures instead of validation-time failures - errors only appear when trying to read records
  3. Poor developer experience - no clear feedback about what's wrong with the schema

Expected Behavior

The declarative component schema should validate that InlineSchemaLoader.schema is a valid JSON Schema conforming to the JSON Schema Draft 7
specification.

Invalid schemas should be caught during manifest validation with clear error messages like:

  • "Invalid JSON Schema type: 'not_a_valid_type' is not a valid type"
  • "Schema must be an object, got string"
  • "Properties must be objects with type definitions"

Proposed Solution

Update the InlineSchemaLoader definition in declarative_component_schema.yaml to validate against the JSON Schema meta-schema.

One approach would be to add a reference to the JSON Schema Draft 7 meta-schema:

InlineSchemaLoader:
  properties:
    schema:
      title: "Schema"
      description: "Describes a streams' schema..."
      type: object
      # Validate that this is a valid JSON Schema
      "$ref": "http://json-schema.org/draft-07/schema#"

Alternatively, add custom validation logic in the CDK to ensure the schema structure is valid before attempting to use it.

Impact

This affects all connector builders using declarative YAML manifests with inline schemas. The fix would:

  • Catch schema errors earlier in the development process
  • Provide clearer error messages
  • Improve developer experience
  • Prevent runtime errors from malformed schemas

Workaround

We've added validation in our MCP server as a temporary workaround, but this should be fixed upstream in the CDK for all users.

Environment

  • CDK version: 6.61.6+ (latest)
  • Component: airbyte_cdk.sources.declarative.declarative_component_schema.yaml
Dominant language
Python
Stars
27
Forks
56
Avg merge
3d 18h
Merged PRs (30d)
30

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from airbytehq/airbyte-python-cdk

All issues in airbytehq/airbyte-python-cdk

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.