Custom Framework/Library Schema

The Custom Framework/Library Schema enables contributors to define framework and library patterns for Code Confluence to detect and analyze across different programming languages. This schema provides a structured way to describe how frameworks and libraries should be identified in codebases.

Quick Reference

Schema: View Full Schema (opens as JSON)
Specification: JSON Schema Draft 2020-12
Organization: By programming language → library → features

Schema Structure

Top Level Structure

The schema organizes definitions hierarchically by language and library:

{
  "python": {
    "fastapi": { /* library definition */ },
    "django": { /* library definition */ }
  },
  "javascript": {
    "express": { /* library definition */ },
    "react": { /* library definition */ }
  }
}

Supported Languages

Prop

Type

Library Definition Structure

Each library definition describes a framework or library that Code Confluence should recognize.

Required Fields

Prop

Type

Optional Fields

Prop

Type

Feature Definition Structure

Each feature within a library describes a specific pattern that Code Confluence should detect.

Required Fields

Prop

Type

`target_level` Values

Prop

Type

`concept` Values

Prop

Type

Concept Examples

AnnotationLike: @app.get("/"), @Component, [HttpGet], @dataclass
CallExpression: mapped_column(), Field(), relationship(), useState()
Inheritance: class User(BaseModel), class MyView(APIView), class App extends Component

`locator_strategy` Values

Prop

Type

Strategy Examples

VariableBound — When app = FastAPI() is used, then @app.get() is detected:

app = FastAPI()  # First: find this binding
@app.get("/")    # Then: find usages of 'app'
def handler(): ...

Direct — When the import is used directly:

from pydantic import BaseModel
class User(BaseModel): ...  # Direct match on 'BaseModel'

Optional Fields

Prop

Type

`construct_query` Properties

Context-Dependent

Available properties depend on the feature's concept value. Use the appropriate regex for your concept type.

Prop

Type

Real Framework Examples

Explore actual schema definitions from the Code Confluence codebase:

FastAPI — Modern, fast web framework for building APIs with Python

Features: HTTP endpoints, background tasks, API router organization

{
  "python": {
    "fastapi": {
      "docs_url": "https://fastapi.tiangolo.com",
      "features": {
        "http_endpoint": {
          "description": "HTTP verb decorator that registers a route handler",
          "absolute_paths": [
            "fastapi.FastAPI",
            "fastapi.applications.FastAPI"
          ],
          "target_level": "function",
          "concept": "AnnotationLike",
          "locator_strategy": "VariableBound",
          "construct_query": {
            "method_regex": "(get|post|put|delete|patch|head|options|trace)"
          },
          "startpoint": true
        },
        "background_tasks": {
          "description": "Background task execution using BackgroundTasks",
          "absolute_paths": [
            "fastapi.BackgroundTasks"
          ],
          "target_level": "function",
          "concept": "CallExpression",
          "locator_strategy": "Direct"
        },
        "api_router": {
          "description": "Route organization using APIRouter",
          "absolute_paths": [
            "fastapi.APIRouter"
          ],
          "target_level": "function",
          "concept": "AnnotationLike",
          "locator_strategy": "VariableBound",
          "construct_query": {
            "method_regex": "(get|post|put|delete|patch|head|options|trace|include_router)"
          },
          "startpoint": true
        }
      }
    }
  }
}

Pydantic — Data validation using Python type annotations

Features: Data models with automatic validation

{
  "python": {
    "pydantic": {
      "docs_url": "https://docs.pydantic.dev",
      "features": {
        "data_model": {
          "description": "Base class for Pydantic models with automatic validation",
          "absolute_paths": [
            "pydantic.BaseModel",
            "pydantic.main.BaseModel"
          ],
          "target_level": "class",
          "concept": "Inheritance",
          "locator_strategy": "Direct"
        }
      }
    }
  }
}

SQLAlchemy — The Python SQL toolkit and ORM

Features: Declarative models, column definitions, relationships

{
  "python": {
    "sqlalchemy": {
      "docs_url": "https://docs.sqlalchemy.org",
      "features": {
        "declarative_base": {
          "description": "Base class for SQLAlchemy declarative models",
          "absolute_paths": [
            "sqlalchemy.ext.declarative.declarative_base",
            "sqlalchemy.orm.declarative_base"
          ],
          "target_level": "class",
          "concept": "Inheritance",
          "locator_strategy": "VariableBound"
        },
        "mapped_column": {
          "description": "Column definition using mapped_column for modern SQLAlchemy",
          "absolute_paths": [
            "sqlalchemy.orm.mapped_column"
          ],
          "target_level": "function",
          "concept": "CallExpression",
          "locator_strategy": "Direct"
        },
        "relationship": {
          "description": "Relationship definition between models",
          "absolute_paths": [
            "sqlalchemy.orm.relationship"
          ],
          "target_level": "function",
          "concept": "CallExpression",
          "locator_strategy": "Direct"
        },
        "column": {
          "description": "Traditional column definition using Column",
          "absolute_paths": [
            "sqlalchemy.Column",
            "sqlalchemy.sql.schema.Column"
          ],
          "target_level": "function",
          "concept": "CallExpression",
          "locator_strategy": "Direct"
        }
      }
    }
  }
}

SQLModel — SQL databases in Python, designed for simplicity

Features: Combines Pydantic and SQLAlchemy — models, fields, relationships

{
  "python": {
    "sqlmodel": {
      "docs_url": "https://sqlmodel.tiangolo.com",
      "features": {
        "sqlmodel_base": {
          "description": "Base class for SQLModel models combining Pydantic and SQLAlchemy",
          "absolute_paths": [
            "sqlmodel.SQLModel"
          ],
          "target_level": "class",
          "concept": "Inheritance",
          "locator_strategy": "Direct"
        },
        "field_definition": {
          "description": "Field definition using Field() function with SQLModel extensions",
          "absolute_paths": [
            "sqlmodel.Field"
          ],
          "target_level": "function",
          "concept": "CallExpression",
          "locator_strategy": "Direct"
        },
        "relationship": {
          "description": "Relationship definition between SQLModel models",
          "absolute_paths": [
            "sqlmodel.Relationship"
          ],
          "target_level": "function",
          "concept": "CallExpression",
          "locator_strategy": "Direct"
        }
      }
    }
  }
}

Complete Multi-Framework Example

Validation Rules

Concept-Target Level Constraints

The schema enforces these mandatory constraints:

CallExpression features must use target_level: "function"
Inheritance features must use target_level: "class"

Violations will cause schema validation to fail.

Pattern Validation

Prop

Type

Best Practices

1. Comprehensive Coverage

Define all major features of a framework/library
Include both common and advanced usage patterns
Cover different ways the same concept might be expressed

2. Accurate Paths

Use fully-qualified import paths
Test paths against actual library documentation
Include version information when patterns change between versions

3. Clear Descriptions

Write human-readable descriptions
Explain the purpose and context of each feature
Include examples in notes when helpful

4. Proper Categorization

Choose appropriate concept values based on how the feature is used
Use startpoint: true for entry points like API endpoints
Set correct target_level based on where the feature applies

5. Strategic Regex Usage

Use construct_query regex patterns to refine matches
Test regex patterns against real code examples
Keep patterns specific enough to avoid false positives

Contributing Schema Updates

To contribute new framework/library definitions:

Fork the repository and create a feature branch
Update the schema file at /static/schemas/custom-framework-lib-schema.json
Add comprehensive definitions following the structure above
Test your definitions against real codebases
Submit a pull request with detailed examples and test cases

Testing Your Schema

Before submitting, verify your schema definitions:

JSON Validation — Ensure the file is valid JSON
Schema Validation — Validate against the JSON Schema specification
Real-world Testing — Test against actual codebases using the framework
Documentation — Ensure all referenced URLs are accessible

Troubleshooting

Common Issues

Future Enhancements

The schema is designed to be extensible. Future versions may include:

Additional programming languages (Rust, C#, Kotlin)
More concept types for different framework constructs
Enhanced query refinement options for complex patterns
Version-aware detection for handling breaking changes between library versions

Custom Framework/Library Schema

View Complete Multi-Framework Schema

Invalid absolute_paths

Missing Required Fields

Concept-Target Level Mismatch

Feature Not Detected

On this page