diff --git a/airbyte_cdk/sources/declarative/declarative_component_schema.yaml b/airbyte_cdk/sources/declarative/declarative_component_schema.yaml index ed4eb0f8b..529c3bfa7 100644 --- a/airbyte_cdk/sources/declarative/declarative_component_schema.yaml +++ b/airbyte_cdk/sources/declarative/declarative_component_schema.yaml @@ -150,16 +150,19 @@ definitions: enum: [ApiKeyAuthenticator] api_token: title: API Key - description: The API key to inject in the request. Fill it in the user inputs. + description: The API key token that will be injected into requests for authentication. This should reference a configuration field that contains the user's API key. Can include formatting like 'Bearer' or 'Token' prefixes. type: string interpolation_context: - config examples: - "{{ config['api_key'] }}" - "Token token={{ config['api_key'] }}" + - "Bearer {{ config['access_token'] }}" + - "{{ config['auth_token'] }}" + - "{{ config['secret_key'] }}" header: title: Header Name - description: The name of the HTTP header that will be set to the API key. This setting is deprecated, use inject_into instead. Header and inject_into can not be defined at the same time. + description: The name of the HTTP header where the API key will be injected. This setting is deprecated, use inject_into instead. Common headers include 'Authorization', 'X-API-Key', or custom headers specific to the API. Header and inject_into cannot be defined at the same time. type: string interpolation_context: - config @@ -167,6 +170,10 @@ definitions: - Authorization - Api-Token - X-Auth-Token + - X-API-Key + - X-RapidAPI-Key + - apikey + - token inject_into: title: Inject API Key Into Outgoing HTTP Request description: Configure how the API Key will be sent in requests to the source API. Either inject_into or header has to be defined. @@ -496,7 +503,7 @@ definitions: enum: [CursorPagination] cursor_value: title: Cursor Value - description: Value of the cursor defining the next page to fetch. + description: Template string for the cursor value to be used in the next request. This should reference a field from the API response that indicates the next page position. type: string interpolation_context: - config @@ -508,12 +515,20 @@ definitions: - "{{ headers.link.next.cursor }}" - "{{ last_record['key'] }}" - "{{ response['nextPage'] }}" + - "{{ response.next_cursor }}" + - "{{ last_record['id'] }}" + - "{{ headers['x-next-page'] }}" + - "{{ response.pagination.next_token }}" page_size: title: Page Size - description: The number of records to include in each pages. + description: The number of records to include in each page. This value will be used with cursor-based pagination to control the amount of data returned per request. Choose a value that balances API rate limits with sync performance. type: integer examples: + - 10 + - 50 - 100 + - 500 + - 1000 stop_condition: title: Stop Condition description: Template string evaluating when to stop paginating. @@ -614,8 +629,15 @@ definitions: examples: - "source_railz.components.MyCustomIncrementalSync" cursor_field: - description: The location of the value on a record that will be used as a bookmark during sync. + title: Cursor Field + description: The location of the value on a record that will be used as a bookmark during sync. This field should contain datetime values that increase over time to enable incremental syncing. The field must be at the top level of the record. type: string + examples: + - "updated_at" + - "created_at" + - "last_modified" + - "timestamp" + - "{{ config['cursor_field'] }}" $parameters: type: object additionalProperties: true @@ -1496,11 +1518,16 @@ definitions: enum: [DeclarativeStream] name: title: Name - description: The stream name. + description: The name of the stream as it will appear in the connector. This should be descriptive and match the data being synced (e.g., 'users', 'orders', 'transactions'). Use lowercase with underscores for consistency. type: string default: "" - example: - - "Users" + examples: + - "users" + - "orders" + - "transactions" + - "events" + - "user_profiles" + - "order_items" retriever: title: Retriever description: Component used to coordinate how records are extracted across stream slices and request pages. @@ -3135,7 +3162,7 @@ definitions: enum: [OffsetIncrement] page_size: title: Limit - description: The number of records to include in each pages. + description: The number of records to include in each page. This value will be used to increment the offset for subsequent requests. Choose a value that balances API rate limits with sync performance. anyOf: - type: integer title: Number of Records @@ -3145,7 +3172,11 @@ definitions: - config - response examples: + - 10 + - 50 - 100 + - 500 + - 1000 - "{{ config['page_size'] }}" inject_on_first_request: title: Inject Offset on First Request @@ -3167,7 +3198,7 @@ definitions: enum: [PageIncrement] page_size: title: Page Size - description: The number of records to include in each pages. + description: The number of records to include in each page. This value will be used to increment the page number for subsequent requests. Choose a value that balances API rate limits with sync performance. interpolation_context: - config anyOf: @@ -3176,7 +3207,11 @@ definitions: - type: string title: Interpolated Value examples: + - 10 + - 50 - 100 + - 500 + - 1000 - "100" - "{{ config['page_size'] }}" start_from_page: @@ -3621,11 +3656,16 @@ definitions: enum: [StateDelegatingStream] name: title: Name - description: The stream name. + description: The name of the stream as it will appear in the connector. This should be descriptive and match the data being synced (e.g., 'users', 'orders', 'transactions'). Use lowercase with underscores for consistency. type: string default: "" - example: - - "Users" + examples: + - "users" + - "orders" + - "transactions" + - "events" + - "user_profiles" + - "order_items" full_refresh_stream: title: Full Refresh Stream description: Component used to coordinate how records are extracted across stream slices and request pages when the state is empty or not provided. @@ -4417,8 +4457,13 @@ definitions: properties: query: type: string - description: The GraphQL query to be executed + description: The GraphQL query to be executed. This should be a valid GraphQL query string that will be sent in the request body. default: "query {\n \n}" + examples: + - "query { users { id name email } }" + - "query GetUser($id: ID!) { user(id: $id) { name email } }" + - "{ viewer { login repositories(first: 10) { nodes { name } } } }" + - "mutation CreateUser($input: UserInput!) { createUser(input: $input) { id } }" additionalProperties: true DpathValidator: title: Dpath Validator diff --git a/airbyte_cdk/sources/declarative/models/declarative_component_schema.py b/airbyte_cdk/sources/declarative/models/declarative_component_schema.py index e20a6a672..96228936c 100644 --- a/airbyte_cdk/sources/declarative/models/declarative_component_schema.py +++ b/airbyte_cdk/sources/declarative/models/declarative_component_schema.py @@ -1,5 +1,3 @@ -# Copyright (c) 2025 Airbyte, Inc., all rights reserved. - # generated by datamodel-codegen: # filename: declarative_component_schema.yaml @@ -106,18 +104,22 @@ class CursorPagination(BaseModel): type: Literal["CursorPagination"] cursor_value: str = Field( ..., - description="Value of the cursor defining the next page to fetch.", + description="Template string for the cursor value to be used in the next request. This should reference a field from the API response that indicates the next page position.", examples=[ "{{ headers.link.next.cursor }}", "{{ last_record['key'] }}", "{{ response['nextPage'] }}", + "{{ response.next_cursor }}", + "{{ last_record['id'] }}", + "{{ headers['x-next-page'] }}", + "{{ response.pagination.next_token }}", ], title="Cursor Value", ) page_size: Optional[int] = Field( None, - description="The number of records to include in each pages.", - examples=[100], + description="The number of records to include in each page. This value will be used with cursor-based pagination to control the amount of data returned per request. Choose a value that balances API rate limits with sync performance.", + examples=[10, 50, 100, 500, 1000], title="Page Size", ) stop_condition: Optional[str] = Field( @@ -187,7 +189,15 @@ class Config: ) cursor_field: str = Field( ..., - description="The location of the value on a record that will be used as a bookmark during sync.", + description="The location of the value on a record that will be used as a bookmark during sync. This field should contain datetime values that increase over time to enable incremental syncing. The field must be at the top level of the record.", + examples=[ + "updated_at", + "created_at", + "last_modified", + "timestamp", + "{{ config['cursor_field'] }}", + ], + title="Cursor Field", ) parameters: Optional[Dict[str, Any]] = Field(None, alias="$parameters") @@ -1195,8 +1205,8 @@ class OffsetIncrement(BaseModel): type: Literal["OffsetIncrement"] page_size: Optional[Union[int, str]] = Field( None, - description="The number of records to include in each pages.", - examples=[100, "{{ config['page_size'] }}"], + description="The number of records to include in each page. This value will be used to increment the offset for subsequent requests. Choose a value that balances API rate limits with sync performance.", + examples=[10, 50, 100, 500, 1000, "{{ config['page_size'] }}"], title="Limit", ) inject_on_first_request: Optional[bool] = Field( @@ -1211,8 +1221,8 @@ class PageIncrement(BaseModel): type: Literal["PageIncrement"] page_size: Optional[Union[int, str]] = Field( None, - description="The number of records to include in each pages.", - examples=[100, "100", "{{ config['page_size'] }}"], + description="The number of records to include in each page. This value will be used to increment the page number for subsequent requests. Choose a value that balances API rate limits with sync performance.", + examples=[10, 50, 100, 500, 1000, "100", "{{ config['page_size'] }}"], title="Page Size", ) start_from_page: Optional[int] = Field( @@ -1573,7 +1583,16 @@ class RequestBodyGraphQlQuery(BaseModel): class Config: extra = Extra.allow - query: str = Field(..., description="The GraphQL query to be executed") + query: str = Field( + ..., + description="The GraphQL query to be executed. This should be a valid GraphQL query string that will be sent in the request body.", + examples=[ + "query { users { id name email } }", + "query GetUser($id: ID!) { user(id: $id) { name email } }", + "{ viewer { login repositories(first: 10) { nodes { name } } } }", + "mutation CreateUser($input: UserInput!) { createUser(input: $input) { id } }", + ], + ) class ValidateAdheresToSchema(BaseModel): @@ -1724,14 +1743,28 @@ class ApiKeyAuthenticator(BaseModel): type: Literal["ApiKeyAuthenticator"] api_token: Optional[str] = Field( None, - description="The API key to inject in the request. Fill it in the user inputs.", - examples=["{{ config['api_key'] }}", "Token token={{ config['api_key'] }}"], + description="The API key token that will be injected into requests for authentication. This should reference a configuration field that contains the user's API key. Can include formatting like 'Bearer' or 'Token' prefixes.", + examples=[ + "{{ config['api_key'] }}", + "Token token={{ config['api_key'] }}", + "Bearer {{ config['access_token'] }}", + "{{ config['auth_token'] }}", + "{{ config['secret_key'] }}", + ], title="API Key", ) header: Optional[str] = Field( None, - description="The name of the HTTP header that will be set to the API key. This setting is deprecated, use inject_into instead. Header and inject_into can not be defined at the same time.", - examples=["Authorization", "Api-Token", "X-Auth-Token"], + description="The name of the HTTP header where the API key will be injected. This setting is deprecated, use inject_into instead. Common headers include 'Authorization', 'X-API-Key', or custom headers specific to the API. Header and inject_into cannot be defined at the same time.", + examples=[ + "Authorization", + "Api-Token", + "X-Auth-Token", + "X-API-Key", + "X-RapidAPI-Key", + "apikey", + "token", + ], title="Header Name", ) inject_into: Optional[RequestOption] = Field( @@ -2426,7 +2459,19 @@ class Config: extra = Extra.allow type: Literal["DeclarativeStream"] - name: Optional[str] = Field("", description="The stream name.", example=["Users"], title="Name") + name: Optional[str] = Field( + "", + description="The name of the stream as it will appear in the connector. This should be descriptive and match the data being synced (e.g., 'users', 'orders', 'transactions'). Use lowercase with underscores for consistency.", + examples=[ + "users", + "orders", + "transactions", + "events", + "user_profiles", + "order_items", + ], + title="Name", + ) retriever: Union[SimpleRetriever, AsyncRetriever, CustomRetriever] = Field( ..., description="Component used to coordinate how records are extracted across stream slices and request pages.", @@ -2789,7 +2834,19 @@ class QueryProperties(BaseModel): class StateDelegatingStream(BaseModel): type: Literal["StateDelegatingStream"] - name: str = Field(..., description="The stream name.", example=["Users"], title="Name") + name: str = Field( + ..., + description="The name of the stream as it will appear in the connector. This should be descriptive and match the data being synced (e.g., 'users', 'orders', 'transactions'). Use lowercase with underscores for consistency.", + examples=[ + "users", + "orders", + "transactions", + "events", + "user_profiles", + "order_items", + ], + title="Name", + ) full_refresh_stream: DeclarativeStream = Field( ..., description="Component used to coordinate how records are extracted across stream slices and request pages when the state is empty or not provided.",