Skip to content

Conversation

lmossman
Copy link
Contributor

@lmossman lmossman commented Jul 17, 2025

The titles, descriptions, and examples of some of the more complex fields in incremental sync and authenticator components were lacking a bit.

This PR updates them to add more detail and examples, and have more professional-looking titles, as these are now all used to power the labels and descriptions we show in the Builder UI.

This will help users when configuring these fields in the UI.

Summary by CodeRabbit

  • Documentation
    • Improved schema and model documentation for datetime-related fields, including detailed descriptions and examples for datetime formats and ISO8601 durations.
    • Clarified default values and added illustrative examples for datetime properties, including current UTC time formatting.
    • Enhanced descriptions and titles for several boolean options and pagination properties to improve clarity and consistency.

@github-actions
Copy link

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Testing This CDK Version

You can test this version of the CDK using the following:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@07-17-update_descriptions_defaults_and_examples_of_complex_fields#egg=airbyte-python-cdk[dev]' --help

# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch 07-17-update_descriptions_defaults_and_examples_of_complex_fields

Helpful Resources

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

  • /autofix - Fixes most formatting and linting issues
  • /poetry-lock - Updates poetry.lock file
  • /test - Runs connector tests with the updated CDK
  • /poe <command> - Runs any poe command in the CDK environment

📝 Edit this welcome message.

Copy link
Contributor Author

lmossman commented Jul 17, 2025

@github-actions
Copy link

github-actions bot commented Jul 17, 2025

PyTest Results (Fast)

3 695 tests  ±0   3 684 ✅ ±0   6m 28s ⏱️ +11s
    1 suites ±0      11 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 683b60b. ± Comparison against base commit 019c027.

♻️ This comment has been updated with latest results.

@lmossman lmossman changed the title update descriptions defaults and examples of complex fields chore: update descriptions defaults and examples of complex fields Jul 17, 2025
@lmossman lmossman requested a review from ChristoGrab July 17, 2025 17:29
@lmossman lmossman marked this pull request as ready for review July 17, 2025 17:30
@github-actions
Copy link

github-actions bot commented Jul 17, 2025

PyTest Results (Full)

3 698 tests  ±0   3 687 ✅ ±0   18m 2s ⏱️ -30s
    1 suites ±0      11 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 683b60b. ± Comparison against base commit 019c027.

♻️ This comment has been updated with latest results.

@lmossman lmossman changed the base branch from lmossman/add-interpolation-context-to-auth-fields to graphite-base/661 July 17, 2025 21:27
@lmossman lmossman force-pushed the 07-17-update_descriptions_defaults_and_examples_of_complex_fields branch from e47ac50 to b7057e4 Compare July 17, 2025 21:27
@lmossman lmossman force-pushed the graphite-base/661 branch from e264808 to 312f2e1 Compare July 17, 2025 21:27
@github-actions github-actions bot added the chore label Jul 17, 2025
@graphite-app graphite-app bot changed the base branch from graphite-base/661 to main July 17, 2025 21:28
@lmossman lmossman force-pushed the 07-17-update_descriptions_defaults_and_examples_of_complex_fields branch from b7057e4 to e8bb2e0 Compare July 17, 2025 21:28
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jul 17, 2025

📝 Walkthrough

Walkthrough

The changes update the schema and Pydantic model definitions for declarative source components, focusing on enriching documentation, descriptions, and examples for datetime formatting and ISO8601 durations. Several fields now include expanded descriptions, more illustrative examples, and clarified default values, particularly for datetime-related properties. No logic or structural changes were made.

Changes

File(s) Change Summary
airbyte_cdk/sources/declarative/declarative_component_schema.yaml Enhanced schema documentation: expanded descriptions, more examples for datetime placeholders and ISO8601 durations, clarified defaults for datetime fields, and reworded boolean flag descriptions.
airbyte_cdk/sources/declarative/models/declarative_component_schema.py Updated Pydantic model field descriptions and examples to match schema changes; added current UTC datetime example, enriched ISO8601 and datetime format documentation, and refined boolean field titles and descriptions.

Sequence Diagram(s)

No sequence diagram is generated, as the changes are limited to documentation and schema enrichment without affecting control flow or feature logic.

Would you like me to suggest adding a quick reference table for the datetime format placeholders somewhere in the docs for easier lookup? Wdyt?

Suggested labels

declarative-component-schema

Suggested reviewers

  • ChristoGrab

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7732298 and 683b60b.

📒 Files selected for processing (2)
  • airbyte_cdk/sources/declarative/declarative_component_schema.yaml (7 hunks)
  • airbyte_cdk/sources/declarative/models/declarative_component_schema.py (7 hunks)
✅ Files skipped from review due to trivial changes (1)
  • airbyte_cdk/sources/declarative/models/declarative_component_schema.py
🚧 Files skipped from review as they are similar to previous changes (1)
  • airbyte_cdk/sources/declarative/declarative_component_schema.yaml
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
  • GitHub Check: Check: source-intercom
  • GitHub Check: Check: source-pokeapi
  • GitHub Check: Check: source-hardcoded-records
  • GitHub Check: Check: destination-motherduck
  • GitHub Check: Check: source-shopify
  • GitHub Check: Pytest (Fast)
  • GitHub Check: Pytest (All, Python 3.10, Ubuntu)
  • GitHub Check: Pytest (All, Python 3.11, Ubuntu)
  • GitHub Check: SDM Docker Image Build
  • GitHub Check: Analyze (python)
✨ Finishing Touches
  • 📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

‼️ IMPORTANT
Auto-reply has been disabled for this repository in the CodeRabbit settings. The CodeRabbit bot will not respond to your replies unless it is explicitly tagged.

  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🔭 Outside diff range comments (1)
airbyte_cdk/sources/declarative/models/declarative_component_schema.py (1)

1879-1900: PT1W is not a legal ISO-8601 duration – should be P1W.
Both the lookback_window and step doc blocks list PT1W for “1 week”. The correct form is P1W ( weeks are expressed without a T time designator ). Updating avoids confusing users and linters, wdyt?

-  * **PT1W**: 1 week
+  * **P1W**: 1 week
🧹 Nitpick comments (4)
airbyte_cdk/sources/declarative/models/declarative_component_schema.py (2)

1805-1817: Missing %s_as_float in the examples list – oversight?
The description lists %s_as_float as a supported placeholder, but the examples that follow omit it. Adding an example such as "%s_as_float" would keep the doc block self-consistent, wdyt?


2515-2519: Same ISO-8601 week typo here (PT1W).
For consistency with the previous comment, this block should also use P1W, wdyt?

airbyte_cdk/sources/declarative/declarative_component_schema.yaml (2)

948-948: Strip the stray trailing spaces?

YAML-lint is flagging an avoidable lint issue on this line – it ends with two spaces.
Removing them keeps the schema free of noisy diffs and helps downstream tooling stay green, wdyt?

-          Use placeholders starting with "%" to describe the format the API is using. The following placeholders are available:␠␠
+          Use placeholders starting with "%" to describe the format the API is using. The following placeholders are available:

1976-1983: Optional: shorten the ISO-8601 cheat-sheet to keep descriptions concise

The five bullet examples are great, but duplicating similar lists in several fields bloats the schema and the generated UI text.
Maybe link to a single authoritative doc (or reuse an $anchor) instead of pasting the same list multiple times, wdyt?

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 312f2e1 and e8bb2e0.

📒 Files selected for processing (2)
  • airbyte_cdk/sources/declarative/declarative_component_schema.yaml (6 hunks)
  • airbyte_cdk/sources/declarative/models/declarative_component_schema.py (6 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: ChristoGrab
PR: airbytehq/airbyte-python-cdk#58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the `YamlDeclarativeSource` class in `airbyte_cdk/sources/declarative/yaml_declarative_source.py`, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the `declarative_component_schema.py` file is auto-generated from `declarative_component_schema.yaml` and should be ignored in the recommended reviewing order.
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (3)

undefined

<retrieved_learning>
Learnt from: ChristoGrab
PR: #58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the YamlDeclarativeSource class in airbyte_cdk/sources/declarative/yaml_declarative_source.py, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
</retrieved_learning>

<retrieved_learning>
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the declarative_component_schema.py file is auto-generated from declarative_component_schema.yaml and should be ignored in the recommended reviewing order.
</retrieved_learning>

<retrieved_learning>
Learnt from: aaronsteers
PR: #58
File: airbyte_cdk/cli/source_declarative_manifest/_run.py:62-65
Timestamp: 2024-11-15T01:04:21.272Z
Learning: The files in airbyte_cdk/cli/source_declarative_manifest/, including _run.py, are imported from another repository, and changes to these files should be minimized or avoided when possible to maintain consistency.
</retrieved_learning>

airbyte_cdk/sources/declarative/models/declarative_component_schema.py (3)

undefined

<retrieved_learning>
Learnt from: ChristoGrab
PR: #58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the YamlDeclarativeSource class in airbyte_cdk/sources/declarative/yaml_declarative_source.py, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
</retrieved_learning>

<retrieved_learning>
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the declarative_component_schema.py file is auto-generated from declarative_component_schema.yaml and should be ignored in the recommended reviewing order.
</retrieved_learning>

<retrieved_learning>
Learnt from: aaronsteers
PR: #58
File: airbyte_cdk/cli/source_declarative_manifest/_run.py:62-65
Timestamp: 2024-11-15T01:04:21.272Z
Learning: The files in airbyte_cdk/cli/source_declarative_manifest/, including _run.py, are imported from another repository, and changes to these files should be minimized or avoided when possible to maintain consistency.
</retrieved_learning>

🪛 YAMLlint (1.37.1)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml

[error] 948-948: trailing spaces

(trailing-spaces)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
  • GitHub Check: Check: destination-motherduck
  • GitHub Check: Check: source-intercom
  • GitHub Check: Check: source-pokeapi
  • GitHub Check: Check: source-hardcoded-records
  • GitHub Check: Check: source-shopify
  • GitHub Check: Pytest (Fast)
  • GitHub Check: Pytest (All, Python 3.11, Ubuntu)
  • GitHub Check: Pytest (All, Python 3.10, Ubuntu)
  • GitHub Check: SDM Docker Image Build
  • GitHub Check: Analyze (python)
🔇 Additional comments (3)
airbyte_cdk/sources/declarative/models/declarative_component_schema.py (2)

986-992: Examples look good – nothing to flag.
The extra now_utc() example adds clarity without affecting validation.


1831-1836: New non-null default may be breaking – double-check downstream assumptions.
end_datetime now defaults to a MinMaxDatetime dict instead of None. Any code that relied on the absence of a value (e.g., if cursor.end_datetime is None) will behave differently. Can you confirm that consumers handle a populated default safely, or consider keeping None and injecting the value later, wdyt?

airbyte_cdk/sources/declarative/declarative_component_schema.yaml (1)

1010-1013: Default object is valid under MinMaxDatetime schema
The MinMaxDatetime definition requires both type and datetime, and also defines datetime_format as an optional property. By default, additionalProperties isn’t set to false, so including datetime_format (and keeping type: MinMaxDatetime) makes the default a valid instance. Dropping the type field would violate the schema’s required constraints. Shall we leave the default as-is? wdyt?

Likely an incorrect or invalid review comment.

@lmossman lmossman force-pushed the 07-17-update_descriptions_defaults_and_examples_of_complex_fields branch from e8bb2e0 to c44f083 Compare July 18, 2025 16:30
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Nitpick comments (2)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (2)

946-980: Minor: strip trailing spaces to appease YAML lint?

yamllint is currently flagging trailing blanks on a few of these doc-lines (e.g. 948, 979). They don’t change runtime behaviour but will keep showing up in CI.

-          The possible formats for the cursor field, in order of preference. The first format that matches the cursor field value will be used to parse it. If not provided, the Outgoing Datetime Format will be used.␠
+          The possible formats for the cursor field, in order of preference. The first format that matches the cursor field value will be used to parse it. If not provided, the Outgoing Datetime Format will be used.

Would you mind trimming those stray spaces so the linter stays green, wdyt?


1976-1983: Nit: same trailing-space issue here

A couple of the bullet lines end with blanks; same comment as above applies.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e8bb2e0 and c44f083.

📒 Files selected for processing (2)
  • airbyte_cdk/sources/declarative/declarative_component_schema.yaml (6 hunks)
  • airbyte_cdk/sources/declarative/models/declarative_component_schema.py (6 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • airbyte_cdk/sources/declarative/models/declarative_component_schema.py
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: ChristoGrab
PR: airbytehq/airbyte-python-cdk#58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the `YamlDeclarativeSource` class in `airbyte_cdk/sources/declarative/yaml_declarative_source.py`, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the `declarative_component_schema.py` file is auto-generated from `declarative_component_schema.yaml` and should be ignored in the recommended reviewing order.
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (3)

undefined

<retrieved_learning>
Learnt from: ChristoGrab
PR: #58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the YamlDeclarativeSource class in airbyte_cdk/sources/declarative/yaml_declarative_source.py, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
</retrieved_learning>

<retrieved_learning>
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the declarative_component_schema.py file is auto-generated from declarative_component_schema.yaml and should be ignored in the recommended reviewing order.
</retrieved_learning>

<retrieved_learning>
Learnt from: aaronsteers
PR: #58
File: airbyte_cdk/cli/source_declarative_manifest/_run.py:62-65
Timestamp: 2024-11-15T01:04:21.272Z
Learning: The files in airbyte_cdk/cli/source_declarative_manifest/, including _run.py, are imported from another repository, and changes to these files should be minimized or avoided when possible to maintain consistency.
</retrieved_learning>

🪛 YAMLlint (1.37.1)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml

[error] 948-948: trailing spaces

(trailing-spaces)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
  • GitHub Check: Check: source-pokeapi
  • GitHub Check: Check: source-hardcoded-records
  • GitHub Check: Check: source-intercom
  • GitHub Check: Check: destination-motherduck
  • GitHub Check: Check: source-shopify
  • GitHub Check: SDM Docker Image Build
  • GitHub Check: Pytest (Fast)
  • GitHub Check: Pytest (All, Python 3.11, Ubuntu)
  • GitHub Check: Pytest (All, Python 3.10, Ubuntu)
  • GitHub Check: Analyze (python)
🔇 Additional comments (7)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (7)

1010-1013: Confirm Builder handles Jinja inside the default object

The default value now contains Jinja ({{ now_utc().strftime(...) }}) as part of a structured object.
Some UIs treat default as a literal and won’t render macros; others evaluate them. Could you double-check that the Builder still shows a sensible pre-filled value and doesn’t serialize the raw template string to users?


1071-1080: Granularity doc looks great

Nice touch adding quick ISO-8601 examples — this should help users pick the right value.


1084-1090: Clearer flag description

The rename clarifies intent; no issues spotted.


1097-1100: 👍 Global cursor explanation reads well

No functional or lint issues noted.


1103-1109: Look-back examples add helpful context

Examples for the common durations are a nice usability win.


1130-1136: Step field docs improved

The extra bullets make the allowed values explicit—looks good.


2764-2764: Example addition is harmless

Including a macro-based example is consistent with other sections.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (1)

946-950: YAML-lint flags trailing whitespace – strip it?

Line 948 still has a pair of trailing spaces, which yamllint is reporting (trailing-spaces).
Although YAML parsers ignore them, our CI rejects schema files that don’t pass yamllint.
Could we remove those two dangling blanks to silence the linter, wdyt?

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c44f083 and 260dbbe.

📒 Files selected for processing (1)
  • airbyte_cdk/sources/declarative/declarative_component_schema.yaml (5 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: ChristoGrab
PR: airbytehq/airbyte-python-cdk#58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the `YamlDeclarativeSource` class in `airbyte_cdk/sources/declarative/yaml_declarative_source.py`, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the `declarative_component_schema.py` file is auto-generated from `declarative_component_schema.yaml` and should be ignored in the recommended reviewing order.
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (3)

undefined

<retrieved_learning>
Learnt from: ChristoGrab
PR: #58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the YamlDeclarativeSource class in airbyte_cdk/sources/declarative/yaml_declarative_source.py, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
</retrieved_learning>

<retrieved_learning>
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the declarative_component_schema.py file is auto-generated from declarative_component_schema.yaml and should be ignored in the recommended reviewing order.
</retrieved_learning>

<retrieved_learning>
Learnt from: aaronsteers
PR: #58
File: airbyte_cdk/cli/source_declarative_manifest/_run.py:62-65
Timestamp: 2024-11-15T01:04:21.272Z
Learning: The files in airbyte_cdk/cli/source_declarative_manifest/, including _run.py, are imported from another repository, and changes to these files should be minimized or avoided when possible to maintain consistency.
</retrieved_learning>

🪛 YAMLlint (1.37.1)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml

[error] 948-948: trailing spaces

(trailing-spaces)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
  • GitHub Check: Check: destination-motherduck
  • GitHub Check: Check: source-intercom
  • GitHub Check: Check: source-pokeapi
  • GitHub Check: Check: source-shopify
  • GitHub Check: Check: source-hardcoded-records
  • GitHub Check: SDM Docker Image Build
  • GitHub Check: Pytest (Fast)
  • GitHub Check: Pytest (All, Python 3.10, Ubuntu)
  • GitHub Check: Pytest (All, Python 3.11, Ubuntu)
  • GitHub Check: Analyze (python)
🔇 Additional comments (1)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (1)

946-980: Nice boost in datetime-format documentation 👏

The expanded cursor_datetime_formats section is much clearer and will definitely help Builder users pick the right placeholders.
No issues spotted with the content itself apart from the tiny whitespace note above.

@lmossman lmossman changed the title chore: update descriptions defaults and examples of complex fields chore: update descriptions and examples of complex fields Jul 18, 2025
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (2)

1099-1105: Same bullet list repeated N times – worth extracting to avoid drift?

lookback_window, step, and expiration_duration now all embed the same five-line cheat-sheet of duration examples. Would moving that into a shared $comment anchor (or a reusable macro/doc link) help us keep the list consistent long-term, wdyt?


1972-1978: Minor: duplicate duration list (see comment above)

Same duplication note as for lookback_window/step.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 260dbbe and 25c35df.

📒 Files selected for processing (1)
  • airbyte_cdk/sources/declarative/declarative_component_schema.yaml (5 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: ChristoGrab
PR: airbytehq/airbyte-python-cdk#58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the `YamlDeclarativeSource` class in `airbyte_cdk/sources/declarative/yaml_declarative_source.py`, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the `declarative_component_schema.py` file is auto-generated from `declarative_component_schema.yaml` and should be ignored in the recommended reviewing order.
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (3)

undefined

<retrieved_learning>
Learnt from: ChristoGrab
PR: #58
File: airbyte_cdk/sources/declarative/yaml_declarative_source.py:0-0
Timestamp: 2024-11-18T23:40:06.391Z
Learning: When modifying the YamlDeclarativeSource class in airbyte_cdk/sources/declarative/yaml_declarative_source.py, avoid introducing breaking changes like altering method signatures within the scope of unrelated PRs. Such changes should be addressed separately to minimize impact on existing implementations.
</retrieved_learning>

<retrieved_learning>
Learnt from: pnilan
PR: airbytehq/airbyte-python-cdk#0
File: :0-0
Timestamp: 2024-12-11T16:34:46.319Z
Learning: In the airbytehq/airbyte-python-cdk repository, the declarative_component_schema.py file is auto-generated from declarative_component_schema.yaml and should be ignored in the recommended reviewing order.
</retrieved_learning>

<retrieved_learning>
Learnt from: aaronsteers
PR: #58
File: airbyte_cdk/cli/source_declarative_manifest/_run.py:62-65
Timestamp: 2024-11-15T01:04:21.272Z
Learning: The files in airbyte_cdk/cli/source_declarative_manifest/, including _run.py, are imported from another repository, and changes to these files should be minimized or avoided when possible to maintain consistency.
</retrieved_learning>

🪛 YAMLlint (1.37.1)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml

[error] 948-948: trailing spaces

(trailing-spaces)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
  • GitHub Check: Check: source-shopify
  • GitHub Check: Pytest (Fast)
  • GitHub Check: Pytest (All, Python 3.11, Ubuntu)
  • GitHub Check: Pytest (All, Python 3.10, Ubuntu)
🔇 Additional comments (3)
airbyte_cdk/sources/declarative/declarative_component_schema.yaml (3)

1066-1076: Is PT0.000001S truly accepted by all ISO-8601 parsers?

Fractional-second durations are allowed by ISO-8601, but some downstream libs (e.g. isodate <2.0) choke on more than millisecond precision. Since the CDK code eventually feeds the string into Python helpers, can we double-check that PT0.000001S will parse everywhere we claim, or perhaps note the library expectation in the description?


1080-1086: “Client-side Incremental Filtering” title update looks good to me

The re-worded title/description is clearer for builder users. 👍


2760-2760: Macro example renders fine

Nice touch showing now_utc().strftime(...) – confirms macro chaining works.

Copy link
Collaborator

@ChristoGrab ChristoGrab left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Nice clarity updates

@lmossman lmossman merged commit d3d94df into main Jul 18, 2025
25 of 26 checks passed
@lmossman lmossman deleted the 07-17-update_descriptions_defaults_and_examples_of_complex_fields branch July 18, 2025 19:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants