You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by mi...@apache.org on 2026/10/13 10:02:18 UTC

(superset) branch master updated: fix(semantic-layer): improve credential entry and connection feedback (#45173)

This is an automated email from the ASF dual-hosted git repository.

aminghadersohi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git


The following commit(s) were added to refs/heads/master by this push:
     new 61a0fd28ec6 fix(semantic-layer): improve credential entry and connection feedback (#45173)
61a0fd28ec6 is described below

commit 61a0fd28ec633bd0df0c822a8d458ac72c219dbb
Author: Mike Bridge <mi...@preset.io>
AuthorDate: Tue Oct 13 04:02:09 2026 -0600

    fix(semantic-layer): improve credential entry and connection feedback (#45173)
---
 .../using-superset/semantic-layer-connections.mdx  |  47 +++
 .../semanticLayers/SemanticLayerModal.test.tsx     | 410 ++++++++++++++++++++-
 .../features/semanticLayers/SemanticLayerModal.tsx |  97 +++--
 .../semanticLayers/jsonFormsAntdRenderers.test.tsx | 260 +++++++++++++
 .../features/semanticLayers/jsonFormsHelpers.tsx   | 125 +++++--
 superset/translations/messages.pot                 |   9 +-
 6 files changed, 876 insertions(+), 72 deletions(-)

diff --git a/docs/docs/using-superset/semantic-layer-connections.mdx b/docs/docs/using-superset/semantic-layer-connections.mdx
new file mode 100644
index 00000000000..1c50184cc08
--- /dev/null
+++ b/docs/docs/using-superset/semantic-layer-connections.mdx
@@ -0,0 +1,47 @@
+---
+title: Semantic layer connections
+---
+
+{/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+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.
+*/}
+
+## Provider-defined connection forms
+
+Installed semantic-layer extensions supply their connection fields and help text.
+Required fields are marked with an asterisk. Examples in empty fields are placeholders,
+not selected values. Follow the provider's field help for optional and conditionally
+required settings.
+
+A nullable password is displayed as one optional password input. Leaving an untouched
+null value blank preserves it; clearing a value sends an empty string. Providers decide
+how these values are interpreted.
+
+Providers can mark a private-key field with `x-input-type: pem` to request a multiline
+editor. Paste the whole key, including matching BEGIN and END lines. The inline check
+only checks the private-key envelope, not cryptographic validity. Password-protected
+keys also need their passphrase. The hint is for private keys, not certificates.
+
+Automatic metadata discovery is debounced. Discovery failures do not prevent entering
+manual values when suggestions are unavailable. Discovery errors use fixed messages
+rather than displaying provider exceptions. Save displays the server's sanitized
+validation reason, such as a duplicate name or missing configuration field, with a
+generic fallback when no reason is available. Saved secrets remain masked while
+editing; configuration changes may require re-entering masked values, as explained
+by the server's validation message. Changing connection dependencies can clear
+dependent selections, so check those fields before saving.
diff --git a/superset-frontend/src/features/semanticLayers/SemanticLayerModal.test.tsx b/superset-frontend/src/features/semanticLayers/SemanticLayerModal.test.tsx
index dbc51956aec..67f278dbaa3 100644
--- a/superset-frontend/src/features/semanticLayers/SemanticLayerModal.test.tsx
+++ b/superset-frontend/src/features/semanticLayers/SemanticLayerModal.test.tsx
@@ -16,7 +16,8 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { SupersetClient } from '@superset-ui/core';
+import { getClientErrorObject, SupersetClient } from '@superset-ui/core';
+import type { JsonSchema } from '@jsonforms/core';
 import {
   act,
   fireEvent,
@@ -28,6 +29,8 @@ import {
 import SemanticLayerModal from './SemanticLayerModal';
 
 let mockJsonFormsChangeTriggered = false;
+let mockFormSchema: JsonSchema | undefined;
+let mockRefreshingSchema = false;
 let capturedOnChange:
   | ((value: { data: Record<string, unknown>; errors?: unknown[] }) => void)
   | null = null;
@@ -37,10 +40,16 @@ jest.mock('@jsonforms/react', () => ({
   JsonForms: ({
     onChange,
     readonly,
+    schema,
+    config,
   }: {
     onChange: (value: unknown) => void;
     readonly?: boolean;
+    schema?: JsonSchema;
+    config?: { refreshingSchema?: boolean };
   }) => {
+    mockFormSchema = schema;
+    mockRefreshingSchema = !!config?.refreshingSchema;
     capturedOnChange = onChange as typeof capturedOnChange;
     // eslint-disable-next-line react-hooks/rules-of-hooks
     if (!mockJsonFormsChangeTriggered) {
@@ -79,21 +88,27 @@ const props = {
 beforeEach(() => {
   mockJsonFormsChangeTriggered = false;
   capturedOnChange = null;
+  mockFormSchema = undefined;
+  mockRefreshingSchema = false;
   jest.useFakeTimers({ advanceTimers: true });
   mockedGet.mockReset();
   mockedPost.mockReset();
+  jest
+    .mocked(getClientErrorObject)
+    .mockReset()
+    .mockResolvedValue({ error: '' });
 
   mockedGet
     .mockResolvedValueOnce({
       json: {
-        result: [{ id: 'snowflake', name: 'Snowflake', description: '' }],
+        result: [{ id: 'example', name: 'Example', description: '' }],
       },
     })
     .mockResolvedValueOnce({
       json: {
         result: {
           name: 'Layer 1',
-          type: 'snowflake',
+          type: 'example',
           configuration: { warehouse: 'wh0' },
         },
       },
@@ -127,7 +142,7 @@ test('posts configuration schema refresh after debounce', async () => {
     expect(mockedPost).toHaveBeenNthCalledWith(1, {
       endpoint: '/api/v1/semantic_layer/schema/configuration',
       jsonPayload: {
-        type: 'snowflake',
+        type: 'example',
         configuration: { warehouse: 'wh0' },
       },
     });
@@ -139,7 +154,7 @@ test('posts configuration schema refresh after debounce', async () => {
     expect(mockedPost).toHaveBeenNthCalledWith(2, {
       endpoint: '/api/v1/semantic_layer/schema/configuration',
       jsonPayload: {
-        type: 'snowflake',
+        type: 'example',
         configuration: { warehouse: 'wh1' },
       },
     });
@@ -168,14 +183,14 @@ test('clears dependent field value when parent dependency changes', async () =>
   mockedGet
     .mockResolvedValueOnce({
       json: {
-        result: [{ id: 'snowflake', name: 'Snowflake', description: '' }],
+        result: [{ id: 'example', name: 'Example', description: '' }],
       },
     })
     .mockResolvedValueOnce({
       json: {
         result: {
           name: 'Layer 1',
-          type: 'snowflake',
+          type: 'example',
           configuration: { database: 'db1' },
         },
       },
@@ -238,6 +253,387 @@ test('cancels pending schema refresh when dependencies become unsatisfied', asyn
   expect(mockedPost).toHaveBeenCalledTimes(1);
 });
 
+test.each([
+  ['debouncing', false],
+  ['pending', false],
+  ['finished', false],
+  ['unsatisfied', false],
+  ['debouncing', true],
+  ['pending', true],
+  ['finished', true],
+  ['unsatisfied', true],
+])(
+  'ignores stale schema completion when newer dependencies are %s (failure: %s)',
+  async (phase, fails) => {
+    mockJsonFormsChangeTriggered = true;
+    props.addDangerToast.mockClear();
+    render(<SemanticLayerModal {...props} />);
+    await waitFor(() => expect(capturedOnChange).not.toBeNull());
+    const initialSchema = mockFormSchema;
+    let finishOld: () => void = () => {};
+    mockedPost.mockReturnValueOnce(
+      new Promise((resolve, reject) => {
+        finishOld = () =>
+          fails
+            ? reject(new Error('stale failure'))
+            : resolve({
+                json: {
+                  result: {
+                    type: 'object',
+                    properties: { obsolete: { type: 'string' } },
+                  },
+                  warning: 'stale warning',
+                },
+              });
+      }),
+    );
+    await act(async () => {
+      capturedOnChange!({ data: { warehouse: 'wh1' }, errors: [] });
+      jest.advanceTimersByTime(501);
+    });
+    expect(mockedPost).toHaveBeenCalledTimes(2);
+    let finishNew: () => void = () => {};
+    mockedPost.mockReturnValueOnce(
+      new Promise(resolve => {
+        finishNew = () =>
+          resolve({
+            json: {
+              result: {
+                type: 'object',
+                properties: { current: { type: 'string' } },
+              },
+            },
+          });
+      }),
+    );
+    await act(async () => {
+      capturedOnChange!({
+        data: { warehouse: phase === 'unsatisfied' ? '' : 'wh2' },
+        errors: [],
+      });
+      if (phase === 'pending' || phase === 'finished')
+        jest.advanceTimersByTime(501);
+    });
+    if (phase === 'finished') await act(async () => finishNew());
+    await act(async () => finishOld());
+    expect(mockFormSchema).toEqual(
+      phase === 'finished'
+        ? { type: 'object', properties: { current: { type: 'string' } } }
+        : initialSchema,
+    );
+    expect(props.addDangerToast).not.toHaveBeenCalled();
+    expect(mockRefreshingSchema).toBe(
+      phase === 'debouncing' || phase === 'pending',
+    );
+    if (phase === 'debouncing')
+      await act(async () => jest.advanceTimersByTime(501));
+    if (phase === 'debouncing' || phase === 'pending') {
+      await act(async () => finishNew());
+      expect(mockFormSchema?.properties).toEqual({
+        current: { type: 'string' },
+      });
+      expect(mockRefreshingSchema).toBe(false);
+    }
+  },
+);
+
+test('Back clears pending refresh state before configuring a provider again', async () => {
+  mockJsonFormsChangeTriggered = true;
+  render(<SemanticLayerModal {...props} semanticLayerUuid={undefined} />);
+  fireEvent.mouseDown(
+    await screen.findByRole('combobox', { name: 'Semantic layer type' }),
+  );
+  fireEvent.click(await screen.findByText('Example'));
+  fireEvent.click(screen.getByRole('button', { name: 'Add' }));
+  await waitFor(() => expect(capturedOnChange).not.toBeNull());
+  let finish: () => void = () => {};
+  mockedPost.mockReturnValueOnce(
+    new Promise(resolve => {
+      finish = () =>
+        resolve({ json: { result: { type: 'object', properties: {} } } });
+    }),
+  );
+  await act(async () => {
+    capturedOnChange!({ data: { warehouse: 'wh1' }, errors: [] });
+    jest.advanceTimersByTime(501);
+  });
+  expect(mockRefreshingSchema).toBe(true);
+  fireEvent.click(screen.getByRole('button', { name: /Back/ }));
+  capturedOnChange = null;
+  fireEvent.click(screen.getByRole('button', { name: 'Add' }));
+  await waitFor(() => expect(capturedOnChange).not.toBeNull());
+  await act(async () => finish());
+  expect(mockRefreshingSchema).toBe(false);
+});
+
+const completeCredentials = {
+  endpoint: 'example-account',
+  credentials: {
+    method: 'key_material',
+    identity: 'synthetic_user',
+    key_material:
+      '-----BEGIN PRIVATE KEY-----\nSYNTHETIC\n-----END PRIVATE KEY-----',
+  },
+};
+const exampleSchema = {
+  type: 'object',
+  properties: {
+    database: {
+      type: 'string',
+      'x-dynamic': true,
+      'x-dependsOn': ['endpoint', 'credentials'],
+    },
+  },
+};
+const safeConfigurationError =
+  'Could not refresh metadata. Check the connection details and your permissions.';
+
+async function setupExampleProvider(
+  configuration: Record<string, unknown> = {},
+) {
+  mockJsonFormsChangeTriggered = true;
+  props.addDangerToast.mockClear();
+  mockedGet.mockReset();
+  mockedGet
+    .mockResolvedValueOnce({
+      json: { result: [{ id: 'example', name: 'Example' }] },
+    })
+    .mockResolvedValueOnce({
+      json: { result: { name: 'Example', type: 'example', configuration } },
+    });
+  mockedPost.mockResolvedValue({ json: { result: exampleSchema } });
+  render(<SemanticLayerModal {...props} />);
+  await waitFor(() => expect(mockedPost).toHaveBeenCalledTimes(1));
+}
+
+test.each([
+  { ...completeCredentials, endpoint: ' ' },
+  {
+    ...completeCredentials,
+    credentials: { ...completeCredentials.credentials, identity: '' },
+  },
+  {
+    ...completeCredentials,
+    credentials: {
+      ...completeCredentials.credentials,
+      key_material: '-----BEGIN PRIVATE KEY-----',
+    },
+  },
+  {
+    ...completeCredentials,
+    credentials: {
+      ...completeCredentials.credentials,
+      key_material: 'XXXXXXXXXX',
+    },
+  },
+  {
+    ...completeCredentials,
+    credentials: {
+      ...completeCredentials.credentials,
+      key_material:
+        '-----BEGIN ENCRYPTED PRIVATE KEY-----\nSYNTHETIC\n-----END ENCRYPTED PRIVATE KEY-----',
+    },
+  },
+])('leaves incomplete credential decisions to the provider: %#', async data => {
+  await setupExampleProvider();
+  await act(async () => {
+    capturedOnChange!({ data, errors: [] });
+    jest.advanceTimersByTime(501);
+  });
+  expect(mockedPost).toHaveBeenCalledTimes(2);
+  expect(mockedPost.mock.calls[1][0].jsonPayload.configuration).toEqual(data);
+});
+
+test('debounces edits without interpreting provider credentials', async () => {
+  await setupExampleProvider();
+  await act(async () => {
+    capturedOnChange!({ data: completeCredentials, errors: [] });
+  });
+  await act(async () => {
+    jest.advanceTimersByTime(300);
+  });
+  expect(mockedPost).toHaveBeenCalledTimes(1);
+  await act(async () => {
+    capturedOnChange!({
+      data: {
+        ...completeCredentials,
+        credentials: {
+          ...completeCredentials.credentials,
+          key_material: 'partial',
+        },
+      },
+      errors: [],
+    });
+  });
+  await act(async () => {
+    jest.advanceTimersByTime(501);
+  });
+  expect(mockedPost).toHaveBeenCalledTimes(2);
+  expect(
+    mockedPost.mock.calls[1][0].jsonPayload.configuration.credentials
+      .key_material,
+  ).toBe('partial');
+  await act(async () => {
+    capturedOnChange!({ data: completeCredentials, errors: [] });
+  });
+  await act(async () => {
+    jest.advanceTimersByTime(501);
+  });
+  expect(mockedPost).toHaveBeenCalledTimes(3);
+  expect(mockedPost.mock.calls[2][0].jsonPayload.configuration).toEqual(
+    completeCredentials,
+  );
+});
+
+test('passes masked credentials to the provider for edit schema and preserves them on Save', async () => {
+  const configuration = {
+    ...completeCredentials,
+    credentials: {
+      ...completeCredentials.credentials,
+      key_material: 'XXXXXXXXXX',
+    },
+  };
+  await setupExampleProvider(configuration);
+  expect(mockedPost.mock.calls[0][0].jsonPayload.configuration).toEqual(
+    configuration,
+  );
+  await act(async () => {
+    capturedOnChange!({ data: configuration, errors: [] });
+  });
+  (SupersetClient.put as jest.Mock).mockResolvedValueOnce({ json: {} });
+  fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+  await waitFor(() =>
+    expect(SupersetClient.put).toHaveBeenCalledWith(
+      expect.objectContaining({
+        jsonPayload: { name: 'Example', configuration },
+      }),
+    ),
+  );
+});
+
+test.each(['warning', 'rejection'])(
+  'replaces refresh %s with a fixed safe message',
+  async mode => {
+    await setupExampleProvider();
+    if (mode === 'warning')
+      mockedPost.mockResolvedValueOnce({
+        json: {
+          result: exampleSchema,
+          warning: 'SECRET <root>: value_error',
+        },
+      });
+    else
+      mockedPost.mockRejectedValueOnce(new Error('SECRET <root>: value_error'));
+    await act(async () => {
+      capturedOnChange!({ data: completeCredentials, errors: [] });
+    });
+    await act(async () => {
+      jest.advanceTimersByTime(501);
+    });
+    await waitFor(() =>
+      expect(props.addDangerToast).toHaveBeenCalledWith(safeConfigurationError),
+    );
+    expect(props.addDangerToast.mock.calls.flat().join()).not.toContain(
+      'SECRET',
+    );
+  },
+);
+
+test('replaces edit-fetch failure with a safe message', async () => {
+  props.addDangerToast.mockClear();
+  mockedPost.mockRejectedValueOnce(new Error('SECRET <root>: value_error'));
+  render(<SemanticLayerModal {...props} />);
+  await waitFor(() =>
+    expect(props.addDangerToast).toHaveBeenCalledWith(
+      'An error occurred while fetching the semantic layer',
+    ),
+  );
+});
+
+test.each([
+  ['create', 'Name already exists: Example'],
+  ['update', 'Name already exists: Example'],
+  ['create', 'Invalid configuration: auth.private_key: missing'],
+  ['update', 'Invalid configuration: auth.private_key: missing'],
+  [
+    'update',
+    'This update changes the configuration while reusing a stored ' +
+      'secret value (a masked field). Provide the real value for any ' +
+      'masked field to confirm a configuration change.',
+  ],
+  ['create', ''],
+  ['update', ''],
+])('preserves the %s Save validation reason: %s', async (mode, message) => {
+  props.addDangerToast.mockClear();
+  props.onHide.mockClear();
+  if (mode === 'update') {
+    await setupExampleProvider(completeCredentials);
+  } else {
+    mockJsonFormsChangeTriggered = true;
+    render(<SemanticLayerModal {...props} semanticLayerUuid={undefined} />);
+    fireEvent.mouseDown(
+      await screen.findByRole('combobox', { name: 'Semantic layer type' }),
+    );
+    fireEvent.click(await screen.findByText('Example'));
+    fireEvent.click(screen.getByRole('button', { name: 'Add' }));
+    await waitFor(() => expect(capturedOnChange).not.toBeNull());
+    act(() => capturedOnChange!({ data: {}, errors: [] }));
+  }
+  jest
+    .mocked(getClientErrorObject)
+    .mockImplementationOnce(
+      jest.requireActual<typeof import('@superset-ui/core')>(
+        '@superset-ui/core',
+      ).getClientErrorObject,
+    );
+  const save = mode === 'update' ? SupersetClient.put : SupersetClient.post;
+  jest
+    .mocked(save)
+    .mockRejectedValueOnce(
+      new Response(JSON.stringify({ message }), { status: 422 }),
+    );
+  const button = screen.getByRole('button', {
+    name: mode === 'update' ? 'Save' : 'Create',
+  });
+  fireEvent.click(button);
+  await waitFor(() =>
+    expect(props.addDangerToast).toHaveBeenCalledWith(
+      message ||
+        (mode === 'update'
+          ? 'An error occurred while updating the semantic layer'
+          : 'An error occurred while creating the semantic layer'),
+    ),
+  );
+  expect(props.onHide).not.toHaveBeenCalled();
+  expect(button).toBeEnabled();
+});
+
+test('Save falls back when the normalized error has no message', async () => {
+  await setupExampleProvider(completeCredentials);
+  (SupersetClient.put as jest.Mock).mockRejectedValueOnce(
+    new Error('SECRET <root>: value_error'),
+  );
+  fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+  await waitFor(() =>
+    expect(props.addDangerToast).toHaveBeenCalledWith(
+      'An error occurred while updating the semantic layer',
+    ),
+  );
+});
+
+test('save failure without credential fields uses neutral operation wording', async () => {
+  props.addDangerToast.mockClear();
+  render(<SemanticLayerModal {...props} />);
+  await waitFor(() => expect(mockedPost).toHaveBeenCalledTimes(1));
+  (SupersetClient.put as jest.Mock).mockRejectedValueOnce(new Error('SECRET'));
+  fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+  await waitFor(() =>
+    expect(props.addDangerToast).toHaveBeenCalledWith(
+      'An error occurred while updating the semantic layer',
+    ),
+  );
+});
+
 test('Reload metadata confirms and closes without navigating away from the toast', async () => {
   mockJsonFormsChangeTriggered = true;
   props.onHide.mockClear();
diff --git a/superset-frontend/src/features/semanticLayers/SemanticLayerModal.tsx b/superset-frontend/src/features/semanticLayers/SemanticLayerModal.tsx
index 0b10f000288..301a2900c97 100644
--- a/superset-frontend/src/features/semanticLayers/SemanticLayerModal.tsx
+++ b/superset-frontend/src/features/semanticLayers/SemanticLayerModal.tsx
@@ -20,7 +20,7 @@ import { useState, useEffect, useCallback, useRef } from 'react';
 import isEqual from 'lodash/isEqual';
 import { t } from '@apache-superset/core/translation';
 import { SupersetClient, getClientErrorObject } from '@superset-ui/core';
-import { Input, Select, Button } from '@superset-ui/core/components';
+import { Form, Input, Select, Button } from '@superset-ui/core/components';
 import { Icons } from '@superset-ui/core/components/Icons';
 import { JsonForms } from '@jsonforms/react';
 import type { JsonSchema, UISchemaElement } from '@jsonforms/core';
@@ -45,11 +45,34 @@ import {
 
 const ModalContent = styled.div`
   padding: ${({ theme }) => theme.sizeUnit * 4}px;
+
+  .ant-form-item {
+    margin-bottom: ${({ theme }) => theme.sizeUnit * 4}px;
+  }
+  .ant-form-item-label {
+    padding-bottom: ${({ theme }) => theme.sizeUnit * 2}px;
+  }
+  .ant-form-item-extra {
+    color: ${({ theme }) => theme.colorTextSecondary};
+    font-size: ${({ theme }) => theme.fontSizeSM}px;
+  }
+  .ant-form-item-required::before {
+    order: 1;
+    margin-inline: ${({ theme }) => theme.sizeUnit / 2}px 0;
+  }
+  .ant-divider {
+    display: none;
+  }
 `;
 
 type Step = 'type' | 'config';
 type ValidationMode = 'ValidateAndHide' | 'ValidateAndShow';
 
+const configurationErrorMessage = () =>
+  t(
+    'Could not refresh metadata. Check the connection details and your permissions.',
+  );
+
 interface SemanticLayerType {
   id: string;
   name: string;
@@ -111,6 +134,7 @@ export default function SemanticLayerModal({
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastDepSnapshotRef = useRef<string>('');
   const dynamicDepsRef = useRef<Record<string, string[]>>({});
+  const schemaRequestRef = useRef(0);
   // Tracks the most recent value we auto-populated into the Name field so we
   // can overwrite it when the user switches type — but leave alone anything
   // the user has hand-edited.
@@ -143,6 +167,8 @@ export default function SemanticLayerModal({
 
   const fetchConfigSchema = useCallback(
     async (type: string, configuration?: Record<string, unknown>) => {
+      schemaRequestRef.current += 1;
+      const request = schemaRequestRef.current;
       const isInitialFetch = !configuration;
       if (isInitialFetch) setLoading(true);
       else setRefreshingSchema(true);
@@ -151,27 +177,24 @@ export default function SemanticLayerModal({
           endpoint: '/api/v1/semantic_layer/schema/configuration',
           jsonPayload: { type, configuration },
         });
+        if (request !== schemaRequestRef.current) return;
         applySchema(json.result);
         if (json.warning) {
-          addDangerToast(String(json.warning));
+          addDangerToast(configurationErrorMessage());
         }
         if (isInitialFetch) setStep('config');
-      } catch (error) {
-        const clientError = await getClientErrorObject(error);
-        if (isInitialFetch) {
-          addDangerToast(
-            clientError.error ||
-              t('An error occurred while fetching the configuration schema'),
-          );
-        } else {
-          addDangerToast(
-            clientError.error ||
-              t('An error occurred while refreshing the configuration schema'),
-          );
-        }
+      } catch {
+        if (request !== schemaRequestRef.current) return;
+        addDangerToast(
+          isInitialFetch
+            ? t('An error occurred while fetching the configuration schema')
+            : configurationErrorMessage(),
+        );
       } finally {
-        if (isInitialFetch) setLoading(false);
-        else setRefreshingSchema(false);
+        if (request === schemaRequestRef.current) {
+          if (isInitialFetch) setLoading(false);
+          else setRefreshingSchema(false);
+        }
       }
     },
     [addDangerToast, applySchema],
@@ -179,11 +202,14 @@ export default function SemanticLayerModal({
 
   const fetchExistingLayer = useCallback(
     async (uuid: string) => {
+      schemaRequestRef.current += 1;
+      const request = schemaRequestRef.current;
       setLoading(true);
       try {
         const { json } = await SupersetClient.get({
           endpoint: `/api/v1/semantic_layer/${uuid}`,
         });
+        if (request !== schemaRequestRef.current) return;
         const layer = json.result;
         setName(layer.name ?? '');
         setSelectedType(layer.type);
@@ -193,24 +219,22 @@ export default function SemanticLayerModal({
           configuration: layer.configuration ?? {},
         });
         setHasErrors(false);
-        // In edit mode, fetch the enriched schema using the full saved
-        // configuration so that dynamic dropdowns (account, project,
-        // environment) show their human-readable labels immediately rather
-        // than flashing raw IDs while the background refresh completes.
+        // Providers decide whether the saved configuration can enrich the schema.
         const { json: schemaJson } = await SupersetClient.post({
           endpoint: '/api/v1/semantic_layer/schema/configuration',
           jsonPayload: { type: layer.type, configuration: layer.configuration },
         });
+        if (request !== schemaRequestRef.current) return;
         applySchema(schemaJson.result);
+        if (schemaJson.warning) addDangerToast(configurationErrorMessage());
         setStep('config');
-      } catch (error) {
-        const clientError = await getClientErrorObject(error);
+      } catch {
+        if (request !== schemaRequestRef.current) return;
         addDangerToast(
-          clientError.error ||
-            t('An error occurred while fetching the semantic layer'),
+          t('An error occurred while fetching the semantic layer'),
         );
       } finally {
-        setLoading(false);
+        if (request === schemaRequestRef.current) setLoading(false);
       }
     },
     [addDangerToast, applySchema],
@@ -248,6 +272,8 @@ export default function SemanticLayerModal({
   useEffect(
     () => () => {
       clearRequestRef.current += 1;
+      schemaRequestRef.current += 1;
+      if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
     },
     [show, semanticLayerUuid],
   );
@@ -293,6 +319,8 @@ export default function SemanticLayerModal({
   };
 
   const handleBack = () => {
+    schemaRequestRef.current += 1;
+    setRefreshingSchema(false);
     setStep('type');
     setConfigSchema(null);
     setUiSchema(undefined);
@@ -363,6 +391,7 @@ export default function SemanticLayerModal({
         areDependenciesSatisfied(deps, data, configSchema ?? undefined),
       );
       if (!hasSatisfiedDeps) {
+        schemaRequestRef.current += 1;
         if (debounceTimerRef.current) {
           clearTimeout(debounceTimerRef.current);
           debounceTimerRef.current = null;
@@ -376,10 +405,11 @@ export default function SemanticLayerModal({
       const snapshot = serializeDependencyValues(dynamicDeps, data);
       if (snapshot === lastDepSnapshotRef.current) return;
       lastDepSnapshotRef.current = snapshot;
+      // Invalidate in-flight results before the next debounced request starts.
+      schemaRequestRef.current += 1;
 
-      // Flip the loading state immediately so dependent fields are disabled
-      // through the debounce window — otherwise the user keeps seeing the
-      // stale options for ~500ms before the request even fires.
+      // Indicate pending discovery through the debounce window without
+      // preventing manual entry while suggestions are unavailable.
       setRefreshingSchema(true);
 
       if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
@@ -502,12 +532,7 @@ export default function SemanticLayerModal({
             {configSchema && (
               // Wrap in a form with autocomplete="off" so browsers do not
               // autofill credential fields (service token, account, etc.).
-              // eslint-disable-next-line jsx-a11y/no-redundant-roles
-              <form
-                role="presentation"
-                autoComplete="off"
-                onSubmit={e => e.preventDefault()}
-              >
+              <Form layout="vertical" autoComplete="off">
                 <JsonForms
                   readonly={clearing}
                   schema={configSchema}
@@ -519,7 +544,7 @@ export default function SemanticLayerModal({
                   validationMode={validationMode}
                   onChange={handleFormChange}
                 />
-              </form>
+              </Form>
             )}
           </>
         )}
diff --git a/superset-frontend/src/features/semanticLayers/jsonFormsAntdRenderers.test.tsx b/superset-frontend/src/features/semanticLayers/jsonFormsAntdRenderers.test.tsx
index 4311cb4d2e0..be2c4243a87 100644
--- a/superset-frontend/src/features/semanticLayers/jsonFormsAntdRenderers.test.tsx
+++ b/superset-frontend/src/features/semanticLayers/jsonFormsAntdRenderers.test.tsx
@@ -16,6 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { useState } from 'react';
 import {
   fireEvent,
   render,
@@ -123,3 +124,262 @@ test('enum control opens an antd 6 dropdown and selects an option', async () =>
     ),
   );
 });
+
+const pemPlaceholder =
+  '-----BEGIN PRIVATE KEY-----\nMIIEv…\n-----END PRIVATE KEY-----';
+
+test('ordinary string controls retain the vendor default display', () => {
+  const schema: JsonSchema = {
+    type: 'object',
+    properties: {
+      schema: { type: 'string', title: 'Schema', default: 'PUBLIC' },
+    },
+  };
+  render(
+    <JsonForms
+      schema={schema}
+      uischema={buildUiSchema(schema)}
+      data={{}}
+      renderers={renderers}
+      cells={cellRegistryEntries}
+    />,
+  );
+  expect(screen.getByRole('textbox', { name: 'Schema' })).toHaveValue('PUBLIC');
+});
+
+test.each([false, true])(
+  'manual fields remain typeable when discovery is pending: %s',
+  refreshingSchema => {
+    const schema = {
+      type: 'object',
+      properties: {
+        database: {
+          type: 'string',
+          title: 'Database',
+          'x-dynamic': true,
+          'x-dependsOn': ['account'],
+        },
+      },
+    } as JsonSchema;
+    render(
+      <JsonForms
+        schema={schema}
+        uischema={buildUiSchema(schema)}
+        data={{}}
+        renderers={renderers}
+        cells={cellRegistryEntries}
+        config={{ refreshingSchema, formData: { account: 'synthetic' } }}
+      />,
+    );
+    expect(screen.getByRole('textbox', { name: 'Database' })).toBeEnabled();
+  },
+);
+test('dynamic text keeps focus and both characters when discovery starts and finishes', async () => {
+  const schema = {
+    type: 'object',
+    properties: {
+      account: { type: 'string', title: 'Account' },
+      database: {
+        type: 'string',
+        title: 'Database',
+        'x-dynamic': true,
+        'x-dependsOn': ['account'],
+      },
+      schema: {
+        type: 'string',
+        title: 'Schema',
+        'x-dynamic': true,
+        'x-dependsOn': ['database'],
+      },
+    },
+  } as JsonSchema;
+  function DiscoveryForm({ finished = false }: { finished?: boolean }) {
+    const [data, setData] = useState<Record<string, unknown>>({
+      account: 'synthetic',
+    });
+    return (
+      <JsonForms
+        schema={schema}
+        uischema={buildUiSchema(schema)}
+        data={data}
+        renderers={renderers}
+        cells={cellRegistryEntries}
+        config={{
+          // The host starts discovery when the dependent field can refresh.
+          refreshingSchema: !!data.database && !finished,
+          formData: data,
+        }}
+        onChange={({ data }: { data: Record<string, unknown> }) =>
+          setData(data)
+        }
+      />
+    );
+  }
+  const { rerender } = render(<DiscoveryForm />);
+  const input = screen.getByRole('textbox', { name: 'Database' });
+  // Allow JSON Forms' debounced onChange to notify the host between keys.
+  await userEvent.type(input, 'ab', { delay: 50 });
+  const currentInput = screen.getByRole<HTMLInputElement>('textbox', {
+    name: 'Database',
+  });
+  expect({
+    value: currentInput.value,
+    sameInput: currentInput === input,
+    focusOnBody: document.activeElement === document.body,
+  }).toEqual({ value: 'ab', sameInput: true, focusOnBody: false });
+  expect(input).toHaveFocus();
+  expect(screen.getByRole('textbox', { name: 'Database' })).toBe(input);
+  rerender(<DiscoveryForm finished />);
+  expect(screen.getByRole('textbox', { name: 'Database' })).toBe(input);
+  expect(input).toHaveValue('ab');
+  expect(input).toHaveFocus();
+});
+
+const keyHelp = 'Paste the whole key, including the BEGIN and END lines.';
+const passwordHelp = 'Leave blank for an unencrypted key.';
+// Pydantic's SecretStr | None inside a discriminated auth union.
+const credentialSchema = {
+  type: 'object',
+  $defs: {
+    PrivateKey: {
+      type: 'object',
+      title: 'Private key',
+      properties: {
+        identity: {
+          type: 'string',
+          title: 'Username',
+          description: 'User for this connection.',
+        },
+        key_material: {
+          type: 'string',
+          title: 'Private key',
+          format: 'password',
+          writeOnly: true,
+          'x-input-type': 'pem',
+          description: keyHelp,
+          examples: [pemPlaceholder],
+        },
+        passphrase: {
+          title: 'Private key password',
+          description: passwordHelp,
+          default: null,
+          anyOf: [
+            { type: 'string', format: 'password', writeOnly: true },
+            { type: 'null' },
+          ],
+        },
+      },
+      required: ['identity', 'key_material'],
+    },
+    Password: {
+      type: 'object',
+      title: 'Password',
+      properties: {
+        password: { type: 'string', format: 'password', title: 'Password' },
+      },
+      required: ['password'],
+    },
+  },
+  properties: {
+    credentials: {
+      title: 'Authentication',
+      oneOf: [{ $ref: '#/$defs/PrivateKey' }, { $ref: '#/$defs/Password' }],
+    },
+  },
+} as JsonSchema;
+
+function setupCredentials(privateKey = '', password?: string | null) {
+  const onChange = jest.fn();
+  render(
+    <JsonForms
+      schema={credentialSchema}
+      uischema={buildUiSchema(credentialSchema)}
+      data={{
+        credentials: {
+          identity: 'synthetic_user',
+          key_material: privateKey,
+          ...(password === undefined ? {} : { passphrase: password }),
+        },
+      }}
+      renderers={renderers}
+      cells={cellRegistryEntries}
+      onChange={onChange}
+    />,
+  );
+  return onChange;
+}
+
+test.each([null, undefined, '', 'XXXXXXXXXX'])(
+  'nullable password is one optional input for %s',
+  async password => {
+    const onChange = setupCredentials('XXXXXXXXXX', password);
+    const input = screen.getByLabelText('Private key password');
+    expect(input).toHaveAttribute('type', 'password');
+    expect(input).toHaveAttribute('autoComplete', 'new-password');
+    expect(input).toHaveValue(password ?? '');
+    expect(screen.queryByText('anyOf-0')).not.toBeInTheDocument();
+    expect(screen.queryByText('anyOf-1')).not.toBeInTheDocument();
+    expect(screen.getByText(passwordHelp)).toBeVisible();
+    // The real auth union remains selectable.
+    expect(screen.getByRole('radio', { name: 'Password' })).toBeInTheDocument();
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(onChange.mock.calls.at(-1)[0].data.credentials.passphrase).toBe(
+      password,
+    );
+    fireEvent.change(input, { target: { value: 'synthetic-passphrase' } });
+    await waitFor(() =>
+      expect(onChange.mock.calls.at(-1)[0].data.credentials.passphrase).toBe(
+        'synthetic-passphrase',
+      ),
+    );
+    fireEvent.change(input, { target: { value: '' } });
+    await waitFor(() =>
+      expect(onChange.mock.calls.at(-1)[0].data.credentials.passphrase).toBe(
+        '',
+      ),
+    );
+  },
+);
+
+test('PEM control preserves newlines and shows its shape and help', async () => {
+  const onChange = setupCredentials();
+  const input = screen.getByRole('textbox', { name: 'Private key' });
+  expect(input.tagName).toBe('TEXTAREA');
+  expect(input).toHaveAttribute('placeholder', pemPlaceholder);
+  expect(input).toHaveAttribute('autoComplete', 'new-password');
+  expect(screen.getByText(keyHelp)).toBeVisible();
+  expect(screen.getByText('User for this connection.')).toBeVisible();
+  const value =
+    '-----BEGIN PRIVATE KEY-----\nSYNTHETIC\n-----END PRIVATE KEY-----';
+  fireEvent.change(input, { target: { value } });
+  await waitFor(() =>
+    expect(onChange.mock.calls.at(-1)[0].data.credentials.key_material).toBe(
+      value,
+    ),
+  );
+  expect(input).toHaveValue(value);
+});
+
+test.each([
+  'SYNTHETIC',
+  '-----BEGIN PRIVATE KEY-----\nSYNTHETIC',
+  '-----BEGIN PRIVATE KEY-----\nSYNTHETIC\n-----END RSA PRIVATE KEY-----',
+])('PEM control explains missing or mismatched boundaries: %s', privateKey => {
+  setupCredentials(privateKey);
+  expect(
+    screen.getByText('Include matching BEGIN and END private key lines.'),
+  ).toBeVisible();
+  expect(screen.getByRole('textbox', { name: 'Private key' })).toBeEnabled();
+});
+
+test('saved masked key does not gain a PEM error or change its value', async () => {
+  const onChange = setupCredentials('XXXXXXXXXX');
+  expect(
+    screen.queryByText('Include matching BEGIN and END private key lines.'),
+  ).not.toBeInTheDocument();
+  await waitFor(() => expect(onChange).toHaveBeenCalled());
+  expect(onChange.mock.calls.at(-1)[0].data.credentials.key_material).toBe(
+    'XXXXXXXXXX',
+  );
+  expect(onChange.mock.calls.at(-1)[0].errors).toEqual([]);
+});
diff --git a/superset-frontend/src/features/semanticLayers/jsonFormsHelpers.tsx b/superset-frontend/src/features/semanticLayers/jsonFormsHelpers.tsx
index 31383ea99d9..ac799b941fc 100644
--- a/superset-frontend/src/features/semanticLayers/jsonFormsHelpers.tsx
+++ b/superset-frontend/src/features/semanticLayers/jsonFormsHelpers.tsx
@@ -27,13 +27,7 @@ import type {
   UISchemaElement,
   ControlProps,
 } from '@jsonforms/core';
-import {
-  rankWith,
-  and,
-  isStringControl,
-  formatIs,
-  schemaMatches,
-} from '@jsonforms/core';
+import { rankWith, and, isStringControl, schemaMatches } from '@jsonforms/core';
 import {
   rendererRegistryEntries,
   TextControl,
@@ -41,32 +35,101 @@ import {
 
 export const SCHEMA_REFRESH_DEBOUNCE_MS = 500;
 
-/**
- * Custom renderer that renders `Input.Password` for fields with
- * `format: "password"` in the JSON Schema (e.g. Pydantic `SecretStr`).
- */
-function PasswordControl(props: ControlProps) {
+/** Check the envelope only; cryptographic validation belongs to the provider. */
+export function hasPemBoundaries(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    /^\s*-----BEGIN ((?:ENCRYPTED |RSA |EC )?PRIVATE KEY)-----[\s\S]+-----END \1-----\s*$/.test(
+      value,
+    )
+  );
+}
+
+/** Only collapse a nullable password, not a genuine choice of auth methods. */
+function nullablePasswordSchema(schema: JsonSchema): JsonSchema | undefined {
+  return schema.anyOf?.length === 2 &&
+    schema.anyOf.some(branch => branch.type === 'null')
+    ? schema.anyOf.find(
+        branch => branch.type === 'string' && branch.format === 'password',
+      )
+    : undefined;
+}
+
+/** Render schema help, nullable passwords and explicitly marked PEM text areas. */
+function SchemaTextControl(props: ControlProps) {
+  const nullablePassword = nullablePasswordSchema(props.schema);
+  const schema = {
+    ...props.schema,
+    ...nullablePassword,
+  } as JsonSchema & {
+    'x-input-type'?: string;
+    examples?: string[];
+  };
+  const pem = schema['x-input-type'] === 'pem';
+  // A saved-secret sentinel is not a newly entered, incomplete PEM value.
+  const missingBoundaries =
+    pem &&
+    typeof props.data === 'string' &&
+    props.data !== '' &&
+    props.data !== 'XXXXXXXXXX' &&
+    !hasPemBoundaries(props.data);
   const uischema = {
     ...props.uischema,
+    formItemProps: {
+      extra: schema.description,
+      ...(
+        props.uischema as UISchemaElement & {
+          formItemProps?: Record<string, unknown>;
+        }
+      ).formItemProps,
+      ...(missingBoundaries
+        ? {
+            help: t('Include matching BEGIN and END private key lines.'),
+            validateStatus: 'error',
+          }
+        : {}),
+    },
     options: {
+      placeholderText: schema.examples?.[0],
       ...props.uischema.options,
-      type: 'password',
+      // The description is visible below the field, not repeated in a tooltip.
+      tooltip: undefined,
+      type: pem
+        ? 'multiline'
+        : schema.format === 'password'
+          ? 'password'
+          : props.uischema.options?.type,
       inputProps: {
         ...((props.uischema.options?.inputProps as Record<string, unknown>) ??
           {}),
         // Prevent browsers from autofilling stored login passwords into
         // service-token fields. 'new-password' is respected even when
         // 'off' is ignored (Chrome ≥ 34).
-        autoComplete: 'new-password',
+        autoComplete: schema.format === 'password' ? 'new-password' : 'off',
+        ...(pem ? { rows: 4, spellCheck: false } : {}),
       },
     },
   };
-  return TextControl({ ...props, uischema });
+  return (
+    <TextControl
+      {...props}
+      data={nullablePassword ? (props.data ?? '') : props.data}
+      schema={schema}
+      uischema={uischema}
+    />
+  );
 }
-const PasswordRenderer = withJsonFormsControlProps(PasswordControl);
-const passwordEntry = {
-  tester: rankWith(3, and(isStringControl, formatIs('password'))),
-  renderer: PasswordRenderer,
+const SchemaTextRenderer = withJsonFormsControlProps(SchemaTextControl);
+const textEntry = {
+  tester: rankWith(3, isStringControl),
+  renderer: SchemaTextRenderer,
+};
+const nullablePasswordEntry = {
+  tester: rankWith(
+    6,
+    schemaMatches(schema => !!nullablePasswordSchema(schema)),
+  ),
+  renderer: SchemaTextRenderer,
 };
 
 /**
@@ -227,18 +290,20 @@ export function DynamicFieldControl(props: ControlProps) {
   );
 
   if (enumValues && enumValues.length > 0) {
-    const tooltip = (props.uischema?.options as Record<string, unknown>)
-      ?.tooltip as string | undefined;
     const placeholder = (props.uischema?.options as Record<string, unknown>)
       ?.placeholderText as string | undefined;
     return (
-      <FormItem label={props.label} tooltip={tooltip}>
+      <FormItem
+        label={props.label}
+        extra={props.schema.description}
+        required={props.required}
+      >
         <Select
           ariaLabel={props.label || undefined}
           value={(props.data as string | number | undefined) ?? undefined}
           onChange={value => props.handleChange(props.path, value)}
           options={options}
-          disabled={!props.enabled || refreshing}
+          disabled={!props.enabled}
           loading={refreshing}
           allowClear
           placeholder={refreshing ? t('Loading...') : placeholder}
@@ -248,7 +313,14 @@ export function DynamicFieldControl(props: ControlProps) {
   }
 
   if (!refreshing) {
-    return TextControl(props);
+    // Keep a suffix mounted: toggling it remounts the input and drops focus.
+    const options = {
+      ...props.uischema.options,
+      inputProps: { suffix: <span /> },
+    };
+    return (
+      <SchemaTextControl {...props} uischema={{ ...props.uischema, options }} />
+    );
   }
 
   const uischema = {
@@ -259,7 +331,7 @@ export function DynamicFieldControl(props: ControlProps) {
       inputProps: { suffix: <Spin size="small" /> },
     },
   };
-  return TextControl({ ...props, uischema, enabled: false });
+  return <SchemaTextControl {...props} uischema={uischema} />;
 }
 const DynamicFieldRenderer = withJsonFormsControlProps(DynamicFieldControl);
 const dynamicFieldEntry = {
@@ -438,7 +510,8 @@ export const multiEnumEntry = {
 
 export const renderers = [
   ...rendererRegistryEntries,
-  passwordEntry,
+  textEntry,
+  nullablePasswordEntry,
   constEntry,
   readOnlyEntry,
   enumNamesEntry,
diff --git a/superset/translations/messages.pot b/superset/translations/messages.pot
index 2f65a4be25b..a7b67c15df2 100644
--- a/superset/translations/messages.pot
+++ b/superset/translations/messages.pot
@@ -1926,9 +1926,6 @@ msgstr ""
 msgid "An error occurred while pruning logs "
 msgstr ""
 
-msgid "An error occurred while refreshing the configuration schema"
-msgstr ""
-
 msgid "An error occurred while refreshing the runtime schema"
 msgstr ""
 
@@ -4129,6 +4126,9 @@ msgstr ""
 msgid "Could not parse the CSS to convert @import rules. Check for syntax errors and try again."
 msgstr ""
 
+msgid "Could not refresh metadata. Check the connection details and your permissions."
+msgstr ""
+
 #, python-format
 msgid "Could not resolve hostname: \"%(host)s\"."
 msgstr ""
@@ -7536,6 +7536,9 @@ msgstr ""
 msgid "Include description to be sent with %s"
 msgstr ""
 
+msgid "Include matching BEGIN and END private key lines."
+msgstr ""
+
 msgid "Include series name as an axis"
 msgstr ""