Skip to content

Conversation

teallarson
Copy link
Contributor

Overview

This PR addresses critical documentation drift between the Sonar implementation and the Airbyte documentation repository. Based on a comprehensive drift analysis performed on 2025-10-08, this update adds missing API documentation for HIGH PRIORITY features that are fully implemented in Sonar but completely undocumented.

Reference: docs-drift-analysis-2025-10-08.md (in sonar repo)

Changes Summary

New Documentation Files (3)

  1. workspaces.md - Workspace Management API

    • List workspaces with cursor-based pagination
    • Get, update, and delete workspaces
    • Workspace statistics and sync operations
    • Complete pagination guide and filtering examples
  2. authentication.md - Complete Authentication Guide

    • All three token types (Operator Bearer, Scoped, Widget)
    • Region selection (US/EU)
    • Template filtering via tags during token generation
    • Token lifecycle management and security best practices
    • 20+ code examples
  3. tags.md - Template Tag Management

    • Tag CRUD operations
    • Tag selection modes (ANY vs ALL)
    • Tagging source and connection templates
    • Tier-based access control examples

Updated Documentation Files (3)

  1. source-templates.md - Enhanced with stream management, PATCH endpoint, tag operations, source definition catalogs

  2. connection-templates.md - Added sync_on_create, non_breaking_changes_preference, cron validation, PATCH endpoint, tag operations

  3. configuring-sources.md - Added region selection, stream management, JMESPath querying, JSON Patch operations

Impact

  • 25+ previously undocumented API endpoints now documented
  • ~2,500 lines of documentation added
  • 100+ code examples
  • 12 HIGH PRIORITY documentation gaps addressed

Validation

All documentation validated against:

  • Sonar codebase at commit 350a75fe73
  • FastAPI route definitions
  • Pydantic schemas
  • Existing documentation style

Breaking Changes

None - Documentation only

This PR addresses critical documentation drift identified in the October 2025
drift analysis. The Sonar implementation has evolved significantly beyond the
current documentation, and this update adds missing API documentation for HIGH
PRIORITY features that are fully implemented but undocumented.

## New Documentation Files

### 1. workspaces.md - Workspace Management API
Complete documentation for workspace management including:
- List workspaces with cursor-based pagination
- Get, update, and delete workspaces
- Workspace statistics and sync operations
- Filtering and pagination examples

### 2. authentication.md - Complete Authentication Guide
Comprehensive authentication documentation covering:
- All three token types (Operator Bearer, Scoped, Widget)
- Region selection (US/EU)
- Template filtering via tags
- Token lifecycle management and security best practices
- Common integration patterns with code examples

### 3. tags.md - Template Tag Management
Central tag management documentation including:
- Tag CRUD operations
- Tag selection modes (ANY vs ALL)
- Tagging source and connection templates
- Filtering workflows and best practices
- Tier-based access control examples

## Updated Documentation Files

### 4. source-templates.md - Enhanced Source Template Documentation
Added missing functionality:
- PATCH endpoint for template updates
- Tag management operations
- Stream management (discover, query, add, update, delete)
- JMESPath catalog querying
- Source definition catalog operations
- JSON Patch examples

### 5. connection-templates.md - Complete Configuration Options
Added missing functionality:
- sync_on_create configuration option
- non_breaking_changes_preference enum values and behavior
- Cron expression validation endpoint
- PATCH endpoint for updates
- Tag management operations
- Multi-tenant and compliance patterns

### 6. configuring-sources.md - Advanced Source Configuration
Added missing functionality:
- Region selection in token generation
- Connection template tag filtering
- Stream management operations
- JMESPath catalog querying
- JSON Patch operations for streams
- Best practices and common workflows

## Impact

This update documents 25+ previously undocumented API endpoints and addresses
12 HIGH PRIORITY documentation gaps:

- Workspace Management API (6 endpoints)
- Stream Operations (5 endpoints)
- Template Tagging System (8 endpoints)
- Authentication details (3 token types, regions, filtering)
- Pagination documentation
- Source Definition Catalogs (6 endpoints)

## Validation

All documentation validated against:
- Sonar codebase at commit 350a75fe73
- FastAPI route definitions
- Pydantic schemas
- Existing documentation style

Reference: docs-drift-analysis-2025-10-08.md
Copy link
Contributor

github-actions bot commented Oct 8, 2025

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Helpful Resources

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions.
    • You can specify a custom changelog by passing changelog. Example: /bump-version changelog="My cool update"
    • Leaving the changelog arg blank will auto-populate the changelog from the PR title.
  • /run-cat-tests - Runs legacy CAT tests (Connector Acceptance Tests)
  • /build-connector-images - Builds and publishes a pre-release docker image for the modified connector(s).
  • JVM connectors:
    • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
      Example: /update-connector-cdk-version connector=destination-bigquery
    • /bump-bulk-cdk-version type=patch changelog='foo' - Bump the Bulk CDK's version. type can be major/minor/patch.
  • Python connectors:
    • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
    • /poe source example lock - Alias for /poe connector source-example lock.
    • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
    • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.

📝 Edit this welcome message.

Copy link
Contributor

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

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

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint

[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Use clear, descriptive names"]

- Use clear, descriptive names


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- any - Template must have a..."]

- `any` - Template must have at least one of the specified tags


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

#### Authentication


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

#### Request Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

#### Response Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

#### Authentication


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Body"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

#### Request Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

#### Response Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

#### Authentication


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

#### Path Parameters


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

#### Request Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

#### Response Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Important Notes"]

#### Important Notes


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

#### Authentication


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

#### Path Parameters


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Body"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

#### Request Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

#### Response Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

#### Authentication


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

#### Path Parameters


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

#### Request Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

#### Response Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

#### Authentication


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

#### Path Parameters


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Body"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

#### Request Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

#### Response Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

#### Authentication


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

#### Path Parameters


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

#### Request Example


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

#### Response Example


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Source templates: Must h..."]

- **Source templates**: Must have "pro-tier" OR "enterprise" tag (`any` mode)


[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Path Parameters"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Path Parameters"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Fields"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Keep your local workspace ca..."]

- Keep your local workspace cache in sync with Airbyte Cloud


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]


[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Fields"]

Copy link
Contributor

github-actions bot commented Oct 8, 2025

Deploy preview for airbyte-docs ready!

✅ Preview
https://airbyte-docs-62houy8v5-airbyte-growth.vercel.app

Built with commit ca11832.
This pull request is being automatically deployed with vercel-action

@teallarson
Copy link
Contributor Author

Updated the agents to run markdown linting and vale (writing style) linting.

Going to have them re-review what they wrote here (not re-run the full analysis).

- Add language specifiers to all code blocks
- Fix spacing around code blocks and lists
- Convert headings to sentence-case per style guide
- Fix terminology (e.g. to for example, Cors to CORS, saas to SaaS)
- Add 35 technical terms to Vale vocabulary
- Update markdownlint config to allow duplicate headings with siblings_only

Resolves 148 total linting errors (114 markdownlint + 34 vale)
@teallarson
Copy link
Contributor Author

@tgonzalezc5 we can decide what to do with this PR, but it contains all of the docs our agents wrote last week that are missing in the embedded docs! I think it's probably worth a review and ship, but not sure how it might conflict with anything you had in flight.

They seem mostly correct (I'm least sure about the schema/catalog things) but should probably be reviewed as though some pretty junior external contractor wrote them IMO.

Would love any feedback you have on how it did, too. We can tweak and improve the agents!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant