Migrate Schema Designer to JAX-RS Apis. Fix some bugs. by epugh · Pull Request #4203 · apache/solr

epugh · 2026-03-10T09:50:01Z

Summary

Migrate the SchemaDesigner to JAX-RS. Fixed a bug in the analyze feature that wasn't working in main.

Changes

JAX-RS adoption, RESTful style routing, and code review. Had to change up the routes in the JavaScript to match.

The runtime behaviour is unchanged.

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…mments Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…y docs guard) Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…ader, sanitize filename Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…/docs map for JS rendering Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…d" ;-)

Copilot

Pull request overview

This PR refactors the Schema Designer v2 API implementation to a Jersey-based resource + OpenAPI-defined interface, updates the admin UI download URL accordingly, and includes a small improvement to JSON-lines parsing to avoid unchecked-cast warnings.

Changes:

Migrate SchemaDesignerAPI from the legacy @EndPoint style to a JerseyResource implementing a new SchemaDesignerApi interface, and update tests to call the new method signatures.
Adjust the Schema Designer UI download endpoint URL to the new /api/schema-designer/download?configSet=... form.
Narrow unchecked-cast suppression in DefaultSampleDocumentsLoader via a helper method using instanceof Map<?, ?>.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
solr/webapp/web/js/angular/controllers/schema-designer.js	Updates Schema Designer download URL to new endpoint shape.
solr/core/src/test/org/apache/solr/handler/designer/TestSchemaDesignerAPI.java	Reworks tests to call new Jersey-style API methods and response handling.
solr/core/src/java/org/apache/solr/handler/designer/SchemaDesignerSettings.java	Changes settings class visibility to `public`.
solr/core/src/java/org/apache/solr/handler/designer/SchemaDesignerConstants.java	Removes unused constants related to old request-param handling.
solr/core/src/java/org/apache/solr/handler/designer/SchemaDesignerConfigSetHelper.java	Minor cleanup/modernization and removal of unused helper logic.
solr/core/src/java/org/apache/solr/handler/designer/SchemaDesignerAPI.java	Major migration to JerseyResource + SchemaDesignerApi, plus download/query response changes.
solr/core/src/java/org/apache/solr/handler/designer/SampleDocuments.java	Uses `Stream.toList()` instead of `Collectors.toList()`.
solr/core/src/java/org/apache/solr/handler/designer/DefaultSchemaSuggester.java	Adjusts field-prop guessing API/signature usage.
solr/core/src/java/org/apache/solr/handler/designer/DefaultSampleDocumentsLoader.java	Introduces `parseStringToJson()` helper and narrows unchecked-cast suppression.
solr/core/src/java/org/apache/solr/core/CoreContainer.java	Registers Schema Designer as a Jersey resource class.
solr/api/src/java/org/apache/solr/client/api/endpoint/SchemaDesignerApi.java	Adds new OpenAPI/JAX-RS interface defining Schema Designer endpoints.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-10T09:59:02Z

    if (errorsDuringIndexing != null) {
-      Map<String, Object> response = new HashMap<>();
-      rsp.setException(
-          new SolrException(
-              SolrException.ErrorCode.BAD_REQUEST,
-              "Failed to re-index sample documents after schema updated."));
-      response.put(ERROR_DETAILS, errorsDuringIndexing);
-      rsp.getValues().addAll(response);
-      return;
+      throw new SolrException(
+          SolrException.ErrorCode.BAD_REQUEST,
+          "Failed to re-index sample documents after schema updated.");
    }


query() used to return an error response containing errorDetails when re-indexing failed, which the Schema Designer UI surfaces (see its errorHandler). This new implementation throws a SolrException without attaching errorDetails, so clients will lose the per-doc failure details. Consider instantiating a FlexibleSolrJerseyResponse early and setting an errorDetails top-level property before throwing, or otherwise preserve the prior error payload structure.

Thanks, I dug in and found some bugs and fixed them in how we surface errors.

Copilot · 2026-03-10T09:59:02Z

+  protected void requireSchemaVersion(Integer schemaVersion) {
+    if (schemaVersion == null) {
      throw new SolrException(
-          SolrException.ErrorCode.BAD_REQUEST,
-          SCHEMA_VERSION_PARAM + " is a required parameter for the " + req.getPath() + " endpoint");
+          SolrException.ErrorCode.BAD_REQUEST, SCHEMA_VERSION_PARAM + " is a required parameter!");
    }
-    return schemaVersion;
  }


requireSchemaVersion() now only rejects null, but previously the API treated -1 as “missing” (since getInt(..., -1) was used) and rejected it. As written, a client can pass schemaVersion=-1 and bypass this validation; it would be safer to also reject negative values to keep the same contract.

…sentinel contract) Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…emadesignerapi-to-v2-annotations

… github.com:epugh/solr into copilot/migrate-schemadesignerapi-to-v2-annotations

epugh · 2026-03-21T15:45:06Z

Discussing with @gerlowskija this ticket, and he brings up the "Shouldn't this be more restFul"? Looking at it, configSet is a query param in ALL of these, and really should be part of the path param.

…ner API Agent-Logs-Url: https://github.com/epugh/solr/sessions/3e11a7a9-caca-4333-8a6b-bbcd5a2cd862 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Agent-Logs-Url: https://github.com/epugh/solr/sessions/8f08e90a-243e-43eb-9aaf-070c2e9ed092 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

epugh · 2026-03-30T10:09:21Z

Replace all FlexibleSolrJerseyResponse usages with the specific typed response POJOs (SchemaDesignerResponse, SchemaDesignerInfoResponse, SchemaDesignerCollectionsResponse, SchemaDesignerSchemaDiffResponse) returned by the SchemaDesigner API methods. Also fix SchemaDesigner.setSchemaObjectField() to handle the add-field and add-field-type action names used by the Schema API request JSON, so that response.field is populated for add-field requests and response.fieldType for add-field-type requests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…r API Agent-Logs-Url: https://github.com/epugh/solr/sessions/507f5cc3-13ae-4824-a6c1-ef4f98052d35 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…i-to-v2-annotations' into copilot/migrate-schemadesignerapi-to-v2-annotations # Conflicts: # solr/core/src/java/org/apache/solr/handler/configsets/DownloadConfigSet.java Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Agent-Logs-Url: https://github.com/epugh/solr/sessions/b74e99f0-20cb-45c6-afa8-b2acdd295385 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…s $resource in JS Agent-Logs-Url: https://github.com/epugh/solr/sessions/adec0806-852d-4a34-a0fb-aef713d8bf76 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

… tests Agent-Logs-Url: https://github.com/epugh/solr/sessions/10ac2a78-7ae6-44d5-858d-e74dd03593ea Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…adesignerapi-to-v2-annotations Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…ddenInConfigSets on ConfigSetService) Agent-Logs-Url: https://github.com/epugh/solr/sessions/8fcb8001-f311-4bcb-bf46-522ebd7a9d05 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…e download+getFile to SchemaDesignerApi Agent-Logs-Url: https://github.com/epugh/solr/sessions/07fed0d8-5175-46b5-bff4-7111da9bb8c3 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…emadesignerapi-to-v2-annotations

… DownloadConfigSet.zipConfigSet() Agent-Logs-Url: https://github.com/epugh/solr/sessions/fd2b245f-2e34-45e1-96fe-a5047e48206b Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

…ownload endpoint directly Agent-Logs-Url: https://github.com/epugh/solr/sessions/4f648089-c8e3-4fcd-9ac5-c55c3e9307df Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

epugh · 2026-04-24T19:29:30Z

We took a diversion to update ConfigsetsAPI with an idea that we would reuse those APIs in the schema designer. Unfortunantly the only reusable API was teh "download a zipped configset". It turns out the other SchemaDesignerAPI endpoints that look like they could be replace with a ConfigsetsAPI call can't be because of Schema Designer specific business logic.

I'll paste below two examples:

listConfigs vs listConfigSets — cannot replace

listConfigSets returns ListConfigsetsResponse { List configSets } — a flat list of all raw configset names, including ._designer_films.

listConfigs does designer-specific logic the JS UI depends on:

Filters out system/excluded configsets and raw .designer* entries from the top-level list
Maps ._designer_X → X (strips the prefix) and marks it as status=0 (draft in progress)
Returns Map<String, Integer> where 0=draft, 1=designer-disabled, 2=enabled — these status integers drive the color coding and filtering in schema-designer.js
listConfigs must stay.

updateFileContents vs uploadConfigSetFile — cannot replace

uploadConfigSetFile (PUT /configsets/{configSetName}/{filePath}) is a general-purpose file upload — it writes bytes to a configset and returns a plain SolrJerseyResponse.

updateFileContents does three critical designer-specific things that uploadConfigSetFile cannot do:

solrconfig.xml pre-validation: Before saving, it loads and parses the XML using InMemoryResourceLoader / SolrConfig.readFromResourceLoader to catch errors before corrupting the configset. The error is returned in the response body (updateFileError + fileContent fields) without touching ZK.
Temp collection reload: After saving, calls configSetHelper.reloadTempCollection(mutableId, false).
Full schema response: Re-indexes sample docs and returns a complete SchemaDesignerResponse (schema fields, settings, doc count, analysis errors).
Name blocker: uploadConfigSetFile calls SolrIdentifierValidator.validateConfigSetName() which rejects names starting with . like ._designer_films, so it literally cannot be used for designer draft configsets.
updateFileContents must stay.

epugh · 2026-04-24T22:15:12Z

I just discovered you can edit a file in a configset via the schemadesigner!

I look forward to having a better edit via Solr UI.

…emadesignerapi-to-v2-annotations

…hen I had to fix this. If we used Rails we wouldn't need this!

gerlowskija · 2026-05-07T19:52:51Z

other SchemaDesignerAPI endpoints that look like they could be replace with a ConfigsetsAPI call can't be because of Schema Designer specific business logic.

Appreciate your writeup on this, thanks @epugh !

If we were designing this from scratch I'd argue some of this stuff should be built into the configset APIs themselves as a general-purpose concept. "Enabled/disabled" in particular seems like a good candidate in that regard. The configset-validation/testing is a bit trickier or more special-purpose, but still...

Anyway, all of that is definitely out of scope for this PR. But thinking aloud in terms of deduplicating this API stuff down the road...

Starting in on review now, will aim to do that from a purely "migration" perspective and not worry about some of the API-duplication concerns I mentioned above...

Copilot AI and others added 8 commits February 22, 2026 14:50

Initial plan

8812129

Migrate SchemaDesignerAPI to JAX-RS V2 annotations

42395bc

Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Address code review feedback: fix copyFrom parameter shadowing and co…

20f4431

…mments Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Fix query() returning no results when sample docs not in memory (empt…

de90529

…y docs guard) Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Fix schema designer download: correct URL, add Content-Disposition he…

912c762

…ader, sanitize filename Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Fix query response structure: wrap SolrDocumentList in numFound/start…

7c16593

…/docs map for JS rendering Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Lint clean ups. "multivalued" is how we spell it ;-) Not "multi-value…

b382a4c

…d" ;-)

code review and manual testing

233162e

github-actions Bot added admin-ui tests cat:api labels Mar 10, 2026

epugh requested a review from Copilot March 10, 2026 09:50

epugh changed the title ~~Fix unchecked cast warning in DefaultSampleDocumentsLoader~~ Migrate Schema Designer to Ja Mar 10, 2026

epugh changed the title ~~Migrate Schema Designer to Ja~~ Migrate Schema Designer to JAX-RS Apis. Fix some bugs. Mar 10, 2026

Copilot started reviewing on behalf of epugh March 10, 2026 09:52 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

epugh added 4 commits March 10, 2026 05:59

track change

11f5209

Finally fix the visibility warning!

6a46d40

Restore surfacing indexing errors.

bcb6a86

Fix error prone.

115fccb

epugh requested review from dsmiley and janhoy March 10, 2026 10:43

Copilot AI and others added 3 commits March 19, 2026 11:57

Fix requireSchemaVersion to also reject negative values (restores -1 …

6756865

…sentinel contract) Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Merge remote-tracking branch 'upstream/main' into copilot/migrate-sch…

c7e0099

…emadesignerapi-to-v2-annotations

Merge branch 'copilot/migrate-schemadesignerapi-to-v2-annotations' of…

810cb96

… github.com:epugh/solr into copilot/migrate-schemadesignerapi-to-v2-annotations

Copilot AI and others added 2 commits March 30, 2026 01:20

Move configSet from query parameter to path parameter in Schema Desig…

c04147f

…ner API Agent-Logs-Url: https://github.com/epugh/solr/sessions/3e11a7a9-caca-4333-8a6b-bbcd5a2cd862 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Use correct HTTP verbs in Schema Designer API (DELETE and PUT)

7f6274c

Agent-Logs-Url: https://github.com/epugh/solr/sessions/8f08e90a-243e-43eb-9aaf-070c2e9ed092 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

epugh requested a review from gerlowskija March 30, 2026 10:10

Copilot AI and others added 21 commits April 2, 2026 15:47

Add clarifying comment to setSchemaObjectField switch

0520952

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Replace FlexibleSolrJerseyResponse with typed POJOs in Schema Designe…

9e3f38d

…r API Agent-Logs-Url: https://github.com/epugh/solr/sessions/507f5cc3-13ae-4824-a6c1-ef4f98052d35 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Add BATS integration test for Schema Designer API endpoints

f53de8f

Agent-Logs-Url: https://github.com/epugh/solr/sessions/b74e99f0-20cb-45c6-afa8-b2acdd295385 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Move getFileContents to ConfigsetsApi/GetConfigSetFile; add Configset…

13a2abf

…s $resource in JS Agent-Logs-Url: https://github.com/epugh/solr/sessions/adec0806-852d-4a34-a0fb-aef713d8bf76 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Reduce mocking: use real FileSystemConfigSetService in configsets API…

b6a69de

… tests Agent-Logs-Url: https://github.com/epugh/solr/sessions/10ac2a78-7ae6-44d5-858d-e74dd03593ea Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Mention new capablities in solrj in changelog

42db2a3

code review

ac0a661

More test coverage

96efd9d

Prevent warning

46d3042

Merge remote-tracking branch 'origin/main' into copilot/migrate-schem…

61f0689

…adesignerapi-to-v2-annotations Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Merge origin/main: pick up ConfigSets revamp (validation, isFileForbi…

fa6fcad

…ddenInConfigSets on ConfigSetService) Agent-Logs-Url: https://github.com/epugh/solr/sessions/8fcb8001-f311-4bcb-bf46-522ebd7a9d05 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Keep only schema designer changes; remove configset additions; restor…

c725d97

…e download+getFile to SchemaDesignerApi Agent-Logs-Url: https://github.com/epugh/solr/sessions/07fed0d8-5175-46b5-bff4-7111da9bb8c3 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Merge remote-tracking branch 'upstream/main' into copilot/migrate-sch…

909988b

…emadesignerapi-to-v2-annotations

Remove duplicate zipConfigSet from SchemaDesignerConfigSetHelper; use…

c4c1e0e

… DownloadConfigSet.zipConfigSet() Agent-Logs-Url: https://github.com/epugh/solr/sessions/fd2b245f-2e34-45e1-96fe-a5047e48206b Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Remove downloadConfig from SchemaDesignerApi; JS uses ConfigsetsApi d…

c0169a2

…ownload endpoint directly Agent-Logs-Url: https://github.com/epugh/solr/sessions/4f648089-c8e3-4fcd-9ac5-c55c3e9307df Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Be able to reuse download configset without magic property

8832e91

Typo fix! Lets be explicit

fa0f2c0

Fix "inprog" error, mostly seen on Schema Designer.

ddba94e

Be user facing!

2216156

Lets reuse a configset api for getting a single file

7b99a0d

epugh added 4 commits April 24, 2026 18:18

tidy

0574d0f

wordsmeith

41d35ed

Merge remote-tracking branch 'upstream/main' into copilot/migrate-sch…

76da361

…emadesignerapi-to-v2-annotations

I hate that I added that super detailed unit test on inputs because t…

ebb31ea

…hen I had to fix this. If we used Rails we wouldn't need this!

remove duplication of tests from bats and junit, follow our bats style

a89880f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate Schema Designer to JAX-RS Apis. Fix some bugs.#4203

Migrate Schema Designer to JAX-RS Apis. Fix some bugs.#4203
epugh wants to merge 49 commits intoapache:mainfrom
epugh:copilot/migrate-schemadesignerapi-to-v2-annotations

epugh commented Mar 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

epugh Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Uh oh!

Uh oh!

epugh commented Mar 21, 2026

Uh oh!

epugh commented Mar 30, 2026

Uh oh!

epugh commented Apr 24, 2026

Uh oh!

epugh commented Apr 24, 2026

Uh oh!

gerlowskija commented May 7, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

epugh commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

epugh Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

epugh commented Mar 21, 2026

Uh oh!

epugh commented Mar 30, 2026

Uh oh!

epugh commented Apr 24, 2026

listConfigs vs listConfigSets — cannot replace

updateFileContents vs uploadConfigSetFile — cannot replace

Uh oh!

epugh commented Apr 24, 2026

Uh oh!

gerlowskija commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

epugh commented Mar 10, 2026 •

edited

Loading

gerlowskija commented May 7, 2026 •

edited

Loading