schema.md

JSON Schema Standards

Connection Schema

Location: openmetadata-spec/src/main/resources/json/schema/entity/services/connections/{service_type}/{moduleName}Connection.json

Minimal Database Schema

{
  "$id": "https://open-metadata.org/schema/entity/services/connections/database/myDbConnection.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "MyDbConnection",
  "description": "MyDb Connection Config",
  "type": "object",
  "javaType": "org.openmetadata.schema.services.connections.database.MyDbConnection",
  "definitions": {
    "myDbType": {
      "description": "Service type.",
      "type": "string",
      "enum": ["MyDb"],
      "default": "MyDb"
    },
    "myDbScheme": {
      "description": "SQLAlchemy driver scheme.",
      "type": "string",
      "enum": ["mydb+pymydb"],
      "default": "mydb+pymydb"
    }
  },
  "properties": {
    "type": {
      "title": "Service Type",
      "description": "Service Type",
      "$ref": "#/definitions/myDbType",
      "default": "MyDb"
    },
    "scheme": {
      "title": "Connection Scheme",
      "description": "SQLAlchemy driver scheme options.",
      "$ref": "#/definitions/myDbScheme",
      "default": "mydb+pymydb"
    },
    "username": { ... },
    "password": { ... },
    "hostPort": { ... },
    "supportsMetadataExtraction": {
      "$ref": "../connectionBasicType.json#/definitions/supportsMetadataExtraction"
    }
  },
  "additionalProperties": false,
  "required": ["hostPort"]
}

Minimal Non-Database Schema

Non-database schemas follow the same structure but without scheme:

{
  "$id": "https://open-metadata.org/schema/entity/services/connections/dashboard/myDashConnection.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "MyDashConnection",
  "description": "MyDash Connection Config",
  "type": "object",
  "javaType": "org.openmetadata.schema.services.connections.dashboard.MyDashConnection",
  "definitions": {
    "myDashType": {
      "description": "Service type.",
      "type": "string",
      "enum": ["MyDash"],
      "default": "MyDash"
    }
  },
  "properties": {
    "type": {
      "title": "Service Type",
      "$ref": "#/definitions/myDashType",
      "default": "MyDash"
    },
    "hostPort": {
      "title": "Host and Port",
      "type": "string",
      "format": "uri"
    },
    "supportsMetadataExtraction": {
      "$ref": "../connectionBasicType.json#/definitions/supportsMetadataExtraction"
    }
  },
  "additionalProperties": false,
  "required": ["hostPort"]
}

Required Fields Guidance

The required array must include all fields needed for a working connection:

• hostPort: Always required
• username + password: Required when the service requires authentication by default (e.g., NTLM, basic auth). Only make optional if the service supports anonymous access as a common deployment
• token / apiKey: Required when token-based auth is the only auth method
• authType: Required when multiple auth methods exist and none is a sensible default

Rule: If omitting a field means the connection will fail with an opaque auth error at runtime, make it required in the schema so the UI validates upfront.

SSL/TLS Configuration

All connectors that communicate over HTTPS should include the SSL config $ref so users can configure certificate verification for enterprise deployments with internal CAs:

"verifySSL": {
    "title": "Verify SSL",
    "description": "Client SSL verification.",
    "$ref": "../../../../security/ssl/verifySSLConfig.json#/definitions/verifySSLConfig",
    "default": "no-ssl"
},
"sslConfig": {
    "title": "SSL Configuration",
    "description": "SSL Configuration details.",
    "$ref": "../../../../security/ssl/verifySSLConfig.json#/definitions/sslConfig"
}

Skip SSL config only for connectors that exclusively use non-TLS protocols (e.g., JDBC with no TLS, local file-based connectors).

Shared $ref Schemas

Auth Schemas (under connections/{service_type}/common/)

Schema	Use For
basicAuth.json	Username + password
iamAuthConfig.json	AWS IAM roles
azureConfig.json	Azure Active Directory
jwtAuth.json	JWT bearer tokens

Capability Flags (under connections/connectionBasicType.json#/definitions/)

Flag	When to Include
supportsMetadataExtraction	Always
supportsUsageExtraction	If usage capability
supportsLineageExtraction	If lineage capability
supportsProfiler	If profiler capability
supportsDBTExtraction	Database connectors
supportsDataDiff	If data diff capability
supportsQueryComment	If query comment supported

Filter Patterns

"databaseFilterPattern": {
    "description": "Regex to only fetch databases that matches the pattern.",
    "$ref": "../../../../type/filterPattern.json#/definitions/filterPattern"
}

Database connectors: databaseFilterPattern, schemaFilterPattern, tableFilterPattern Dashboard connectors: dashboardFilterPattern, chartFilterPattern, projectFilterPattern Pipeline connectors: pipelineFilterPattern Messaging connectors: topicFilterPattern

Test Connection JSON

Location: openmetadata-service/src/main/resources/json/data/testConnections/{service_type}/{moduleName}.json

{
  "name": "MyDb",
  "displayName": "MyDb Test Connection",
  "description": "Validate that we can connect and extract metadata from MyDb.",
  "steps": [
    {
      "name": "CheckAccess",
      "description": "Validate access to the service",
      "errorMessage": "Failed to connect to MyDb",
      "mandatory": true,
      "shortCircuit": true
    },
    {
      "name": "GetDatabases",
      "description": "List available databases",
      "errorMessage": "Failed to list databases",
      "mandatory": true,
      "shortCircuit": false
    }
  ]
}

Step names must exactly match keys in the test_fn dict returned by connection.py.

Service Registration Schema

Location: openmetadata-spec/.../entity/services/{serviceType}Service.json

Add two things:

1. The connector name to the serviceType enum array
2. A $ref entry to the connection oneOf array:

{
    "$ref": "../../connections/{service_type}/{moduleName}Connection.json"
}