OpenMetadata/skills/standards/code_style.md

Code Style Standards

Python

Imports

Order: stdlib → third-party → OpenMetadata generated → OpenMetadata internal

import json
import traceback
from functools import partial
from typing import Iterable, Optional

import requests
from sqlalchemy.engine import Engine

from metadata.generated.schema.entity.services.connections.database.myDbConnection import (
    MyDbConnection,
)
from metadata.ingestion.api.models import Either
from metadata.ingestion.connections.connection import BaseConnection
from metadata.utils.logger import ingestion_logger

Naming

• Connector directory: snake_case (e.g., my_database)
• Python classes: PascalCase (e.g., MyDatabaseSource)
• JSON Schema file: lowerCamelCase + Connection.json (e.g., myDatabaseConnection.json)
• Type enum: PascalCase (e.g., MyDatabase)

Type Annotations

• All function signatures must have type annotations
• Use Optional[T] for nullable fields
• Use Iterable[Either[...]] for yield methods
• Import types from typing or collections.abc

No Unnecessary Comments

• Do NOT add comments that describe what code obviously does
• Only comment complex business logic, non-obvious algorithms, or workarounds
• No Google-style docstrings with Args: / Returns: on simple methods
• If code needs a comment to be understood, refactor the code instead

Pydantic Models

When defining Pydantic models for API responses with aliased fields:

• Always set model_config = ConfigDict(populate_by_name=True) when using Field(alias=...) — without it, constructing instances with Python attribute names raises ValidationError
• Use Optional[T] with Field(None, alias=...) for nullable fields
• Create list response wrapper models inheriting from a base OData/pagination response

from pydantic import BaseModel, ConfigDict, Field

class MyApiReport(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    id: str = Field(alias="Id")
    name: str = Field(alias="Name")
    description: Optional[str] = Field(None, alias="Description")


class MyApiListResponse(BaseModel):
    value: List[MyApiReport] = Field(default_factory=list)

Error Messages

Include context in error messages:

# Good
raise ValueError(f"Cannot connect to {config.hostPort}: {exc}")

# Bad
raise ValueError("Connection failed")

JSON Schema

File Naming

Schema file names use lowerCamelCase:

• myDatabaseConnection.json (not my_database_connection.json)
• bigQueryConnection.json (not big_query_connection.json)

Required Fields

Every connection schema must have:

• $id with full URI path
• $schema: http://json-schema.org/draft-07/schema#
• title: PascalCase connection name
• javaType: Full Java class path
• type: "object"
• definitions block with type enum
• additionalProperties: false

Property Conventions

• Use title for UI labels
• Use description for help text
• Use format: "password" for secrets
• Use format: "uri" for URLs
• Use default values where sensible
• Use $ref to compose from shared schemas

$ref Paths

Paths are relative from the schema file location:

• Auth: ./common/basicAuth.json
• SSL: ../../../../security/ssl/verifySSLConfig.json#/definitions/sslConfig
• Filters: ../../../../type/filterPattern.json#/definitions/filterPattern
• Connection extras: ../connectionBasicType.json#/definitions/connectionOptions
• Capability flags: ../connectionBasicType.json#/definitions/supportsMetadataExtraction

Copyright Header

All Python files must start with:

#  Copyright 2025 OpenMetadata
#  Licensed under the Collate Community License, Version 1.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#  https://github.com/open-metadata/OpenMetadata/blob/main/ingestion/LICENSE
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.

Formatting

• Python: ruff (lint + format, run make py_format to apply, make py_format_check to verify)
• Java: spotless (run mvn spotless:apply)
• Line length: 120

Always run formatting before committing:

source env/bin/activate
make py_format
mvn spotless:apply

If make py_format fails because tools are not installed:

source env/bin/activate
make install_dev generate
make py_format

Pre-Merge Cleanup

CONNECTOR_CONTEXT.md is gitignored and stays local — no action needed for that file.

Before submitting a PR, verify:

• No scaffolding artifacts are staged (check git status — CONNECTOR_CONTEXT.md should not appear)
• Remove any TODO comments that are implementation instructions (keep only genuine future-work TODOs with ticket references)
• Remove any temporary test fixtures or mock data files that aren't part of the test suite