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.

solr/webapp/web/js/angular/controllers/schema-designer.js

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

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesigner.java

    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

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesigner.java

+  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.

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesignerSettings.java

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesignerAPI.java

…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

gerlowskija

Just started looking through this and had a few initial comments.

I'm really hesitant to ask larger questions about these schema-designer APIs that would really bog down this PR. But to toe the line on that front: so many of these APIs (e.g. GET /schema-designer/configs, DELETE /schema-designer/<configset>) look nearly identical to CRUD APIs that already exist for configsets. Which seems at least somewhat suspect...

Maybe we're better off holding off on any REST-ful-ness changes in this PR, so that we can give some of those questions the time/attention they deserve rather than lumping them in here?

gerlowskija · 2026-03-31T16:31:58Z

changelog/unreleased/SOLR-18152-migrate-schemadesignerapi-to-v2-annotations.yml

@@ -0,0 +1,8 @@
+# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc
+title: Migrate Schema Designer API to JAX-RS.  Fix bug preventing analysis of sample documents from running.


[-0] This is user-facing text - why would a user care what framework we use in our server-side code?

For most APIs I generally make the changelog entry about the new SolrJ SolrRequest/SolrResponse that'll be generated. That may make sense here as well? But also - these APIs are so UI-centric that it's hard to imagine anyone ever calling them from Java code. Without a use case there, even that sort of a changelog entry might not make sense...

Maybe the changelog here should "just" highlight the bug fix and give a bit more detail on that?

gerlowskija · 2026-03-31T16:54:35Z

solr/api/src/java/org/apache/solr/client/api/endpoint/SchemaDesignerApi.java

+import org.apache.solr.client.api.model.SolrJerseyResponse;
+
+/** V2 API definitions for the Solr Schema Designer. */
+@Path("/schema-designer")


[Q] This comment aims to summarize the cosmetic changes you've made here. But that comment itself looks off somehow.

Looking at the actual code here, each API has a /schema-designer path prefix that just isn't mentioned in the proposal at all.

Further the "Before" column doesn't appear to actually represent the APIs as they exist today on main. Rather the column appears to represent some intermediate state in your PR's development (i.e. after you moved the configset param in to the path). Which is kindof misleading in terms of understanding the "net" change being proposed.

Was this intentional? (e.g. /schema-designer was omitted for concise-ness) Or am I maybe missing something here?

I'm going to largely skip review of this file for now given some of the uncertainties above, but happy to review those later on.

gerlowskija

Alright - I've still largely held off from reviewing the actual cosmetics of the APIs laid out in SchemaDesignerApi (and correspondingly skipped the '.js' files).

But otherwise I've reviewed most of this and highlighted a handful of things that probably need changed here to fit with how we've been using JAX-RS elsewhere. Lmk if you have any questions!

gerlowskija · 2026-03-31T18:39:42Z

solr/api/src/java/org/apache/solr/client/api/endpoint/SchemaDesignerApi.java

+import org.apache.solr.client.api.model.SolrJerseyResponse;
+
+/** V2 API definitions for the Solr Schema Designer. */
+@Path("/schema-designer")


I'm going to largely skip review of this file for now given some of the uncertainties above, but happy to review those later on.

gerlowskija · 2026-03-31T18:48:47Z

solr/api/src/java/org/apache/solr/client/api/endpoint/SchemaDesignerApi.java

+  @Operation(
+      summary = "Get info about a configSet being designed.",
+      tags = {"schema-designer"})
+  FlexibleSolrJerseyResponse getInfo(@PathParam("configSet") String configSet) throws Exception;


[-0] Why use 'FlexibleSolrJerseyResponse' here as opposed to some more tailored POJO type? AFAICT from the implementing code, the response has 4 or 5 top-level properties and modeling as a POJO should be pretty doable.

Ditto for several of the other endpoints here as well.

gerlowskija · 2026-03-31T19:04:39Z

solr/core/src/java/org/apache/solr/handler/designer/DefaultSampleDocumentsLoader.java


+  private void parseStringToJson(List<Map<String, Object>> docs, String line) throws IOException {
+    line = line.trim();
+    if (line.startsWith("{") && line.endsWith("}")) {


[Q] Previous version had !line.isEmpty() condition here. Is there a reason that was removed?

gerlowskija · 2026-03-31T19:14:38Z

solr/core/src/java/org/apache/solr/handler/designer/DefaultSchemaSuggester.java

-      List<Object> sampleValues,
-      boolean isMV,
-      IndexSchema schema) {
+      String fieldName, FieldType fieldType, boolean isMV, IndexSchema schema) {


[0] Is this just an opportunistic refactor that removes an unused parameter (i.e. 'sampleValues')?

I'm fine with this one, but in future I'd prefer if you leave these out of these "purely JAX-RS migration" PRs. Just makes the diff harder to read and opens the door to subtle bugs slipping in, is all.

gerlowskija · 2026-03-31T19:16:59Z

solr/core/src/java/org/apache/solr/handler/designer/SampleDocuments.java

                        && !ids.contains(id); // doc has ID, and it's not already in the set
                  })
-              .collect(Collectors.toList());
+              .toList();


Ditto, re: unrelated tweaks/refactors making this harder to review and vet.

gerlowskija · 2026-03-31T20:24:06Z

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesigner.java

-      int rf = req.getParams().getInt("replicationFactor", 1);
-      configSetHelper.createCollection(newCollection, configSet, numShards, rf);
-      if (req.getParams().getBool(INDEX_TO_COLLECTION_PARAM, false)) {
+      configSetHelper.createCollection(newCollection, configSet, numShards, replicationFactor);


[-1] Ditto, re: triggering an NPE if 'numShards', 'replicationFactor', etc. aren't specified.

The existing code uses particular defaults (1) here as well that we should probably be making sure the newer code uses

gerlowskija · 2026-03-31T20:29:41Z

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesigner.java

+    qr.getResponse()
+        .forEach(
+            (name, val) -> {
+              if ("response".equals(name) && val instanceof SolrDocumentList) {


[Q] Can you add some context on this part of the PR please?

gerlowskija · 2026-03-31T20:30:42Z

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesigner.java

@@ -1106,7 +1162,7 @@ protected long waitToSeeSampleDocs(String collectionName, long numAdded)
    return numFound;
  }

-  protected Map<String, Object> buildResponse(
+  Map<String, Object> buildResponse(


[Q] Why the visibility change?

gerlowskija · 2026-03-31T20:31:26Z

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesigner.java

@@ -1260,8 +1316,7 @@ protected Map<String, Object> readJsonFromRequest(SolrQueryRequest req) throws I
    return (Map<String, Object>) json;
  }

-  protected void addSettingsToResponse(
-      SchemaDesignerSettings settings, final Map<String, Object> response) {
+  void addSettingsToResponse(SchemaDesignerSettings settings, final Map<String, Object> response) {


[Q] Why the visibility-changes on some of these methods?

gerlowskija · 2026-03-31T20:35:22Z

solr/core/src/java/org/apache/solr/handler/designer/SchemaDesignerConfigSetHelper.java

-              .filter(df -> langFieldTypeNames.contains(df.getPrototype().getType().getTypeName()))
-              .filter(df -> !existingDynFields.contains(df.getPrototype().getName()))
              .map(IndexSchema.DynamicField::getPrototype)
+              .filter(prototype -> langFieldTypeNames.contains(prototype.getType().getTypeName()))


[Q] What's the rationale for moving this down below the map(...). It seems unrelated to the JAX-RS migration unless I'm missing something?

…igSet Agent-Logs-Url: https://github.com/epugh/solr/sessions/b4bd2d0e-f388-4fa4-8e0a-6df9ef796863 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

changelog/unreleased/SOLR-18152-add-configset-download-zip-to-solrj-fix-schema-designer-bug.yml

…playName query param Agent-Logs-Url: https://github.com/epugh/solr/sessions/eff3e08e-97a3-4e83-832c-74cc41e9058d Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

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>

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

gerlowskija reviewed Mar 31, 2026

View reviewed changes

gerlowskija requested changes Mar 31, 2026

View reviewed changes

Move downloadConfig to reusable ConfigsetsApi.Download / DownloadConf…

d05be2f

…igSet Agent-Logs-Url: https://github.com/epugh/solr/sessions/b4bd2d0e-f388-4fa4-8e0a-6df9ef796863 Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

epugh commented Apr 2, 2026

View reviewed changes

changelog/unreleased/SOLR-18152-add-configset-download-zip-to-solrj-fix-schema-designer-bug.yml Show resolved Hide resolved

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

Move schema-designer download to generic configsets endpoint; add dis…

0881dba

…playName query param Agent-Logs-Url: https://github.com/epugh/solr/sessions/eff3e08e-97a3-4e83-832c-74cc41e9058d Co-authored-by: epugh <22395+epugh@users.noreply.github.com>

Use our standard naming pattern that the Api is in the endpoint package

b021f15

Rework changelog

9667896

Use same style for all class intro javadocs.

91be03c

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

		@@ -0,0 +1,8 @@
		# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc
		title: Migrate Schema Designer API to JAX-RS. Fix bug preventing analysis of sample documents from running.

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!

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!

gerlowskija left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gerlowskija left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

epugh commented Mar 10, 2026 •

edited

Loading