Documentation > Configuration

Move from schema.xml to managed-schema

Configuration

To move from using the classic schema.xml in your opensolr index, to the managed-schema simply follow the steps below:

In your solrconfig.xml, look for a SchemaFactory definition, and replace it with this snippet:

   <schemaFactory class="ManagedIndexSchemaFactory">
      <bool name="mutable">true</bool>
      <str name="managedSchemaResourceName">managed-schema</str>
   </schemaFactory>

If you don't have any schemaFactory definition, just paste the above snippet to your solrconfig.xml file, just about any requestHandler definition.

Why Move to Managed-Schema?

There are several reasons you might want to switch from the classic schema.xml approach to managed-schema:

  • Schema API Support: Managed-schema enables the Solr Schema API, which allows you to add, modify, and delete fields via REST endpoints without manually editing XML files.
  • Dynamic Field Management: Applications like Drupal's Search API Solr module rely on the Schema API to automatically configure fields. If your integration requires it, managed-schema is the way to go.
  • Programmatic Schema Changes: If you need to update your schema from code (CI/CD pipelines, deployment scripts), the Schema API makes this straightforward with simple HTTP requests.

Step-by-Step Migration Instructions

  1. Open the Config Files Editor in your Opensolr Index control panel.
  2. Edit solrconfig.xml and locate the schemaFactory section. If you see ClassicIndexSchemaFactory, replace it with the ManagedIndexSchemaFactory snippet shown above. If there is no schemaFactory section at all, add the snippet just before any <requestHandler> definition.
  3. Save the file in the Config Files Editor.
  4. Reload your Opensolr Index by clicking the Reload button in the control panel.
  5. After the reload, Solr will automatically read your existing schema.xml and create a new managed-schema file from it. Your original schema.xml is preserved but will no longer be used.

What Changes in solrconfig.xml

The key change is the schemaFactory class. Here is a comparison:

Classic mode (schema.xml):

<schemaFactory class="ClassicIndexSchemaFactory"/>

Managed mode (managed-schema):

<schemaFactory class="ManagedIndexSchemaFactory">
  <bool name="mutable">true</bool>
  <str name="managedSchemaResourceName">managed-schema</str>
</schemaFactory>

Setting mutable to true allows the Schema API to modify the schema at runtime. If you set it to false, the managed-schema is read-only and the Schema API will reject modification requests.

Common Pitfalls

  • Leaving both schemaFactory definitions: If your solrconfig.xml contains both ClassicIndexSchemaFactory and ManagedIndexSchemaFactory, Solr will fail to start. Make sure you remove the old definition entirely before adding the new one.
  • Editing managed-schema manually: Once you switch to managed mode, avoid editing the managed-schema file directly through the Config Files Editor. Use the Schema API instead. Manual edits can be overwritten by Solr on reload.
  • Forgetting to reload: The migration only happens when the index is reloaded after the solrconfig.xml change. If you just save without reloading, nothing changes.
  • Schema.xml syntax errors: If your existing schema.xml has syntax errors, the migration will fail on reload. Check the Error Log and fix any issues in schema.xml first, then switch the schemaFactory.

How to Verify the Migration Worked

  1. After reloading, check the Error Log in your Opensolr control panel. A clean reload with no errors means the migration succeeded.
  2. Try making a Schema API call to list your fields. You can do this with a simple cURL command: 
    curl "https://YOUR_HOSTNAME/solr/YOUR_CORE/schema/fields"
    If you get a JSON response listing your fields, the Schema API is active and working.
  3. Verify that your existing fields and field types are intact by checking the response from the Schema API against your original schema.xml definitions.

If you ever need to switch back to classic schema.xml mode, see our FAQ on fixing schema.xml not taking effect, which explains how to restore the ClassicIndexSchemaFactory.