REST properties format change

Ticket #188 led to a change in how properties.xml is formatted. Here's the original format:

<?xml version="1.0" encoding="UTF-8"?>
<map:map xmlns:map="http://marklogic.com/xdmp/map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <map:entry key="content-versions">
    <map:value xsi:type="xs:string">none</map:value>
  </map:entry>
  <map:entry key="validate-options">
    <map:value xsi:type="xs:boolean">true</map:value>
  </map:entry>
  <map:entry key="document-transform-out">
    <map:value xsi:type="xs:string"/>
  </map:entry>
  <map:entry key="debug">
    <map:value xsi:type="xs:boolean">false</map:value>
  </map:entry>
  <map:entry key="error-format">
    <map:value xsi:type="xs:string">xml</map:value>
  </map:entry>
  <map:entry key="validate-queries">
    <map:value xsi:type="xs:boolean">false</map:value>
  </map:entry>
  <map:entry key="can-copy">
    <map:value xsi:type="xs:boolean">true</map:value>
  </map:entry>
</map:map>

This is a serialized map -- it's the set of properties as you'd see them if you go poking around in a modules database. However, that's not how the REST API expects to receive them. When you PUT your properties to the REST API at /v1/config/properties (as Roxy now does), they need to be in this format:

<properties xmlns="http://marklogic.com/rest-api">
  <content-versions>none</content-versions>
  <validate-options>true</validate-options>
  <document-transform-out></document-transform-out>
  <debug>false</debug>
  <error-format>xml</error-format>
  <validate-queries>false</validate-queries>
</properties>

What do I need to do?

You may have gotten a message from Roxy saying "properties.xml is in an old format; changes to this file won't take effect." Or if your Roxy files aren't new enough to give you that warning, you may have seen the XDMP-NONMIXEDCOMPLEXCONT error. Here's how to fix it:

• copy the new format above into your rest-api/config/properties.xml file, leaving the original there;
• check for any changed property values and update the new properties accordingly
• delete the original (map:map)
• if you're seeing the XDMP-NONMIXEDCOMPLEXCONT error, you'll need to upgrade Roxy (./ml upgrade -h)

Why the change? Couldn't you have just left it alone?

Sadly, no -- that would have been easier for both of us. By deploying properties the old way (XCC dump into the modules database), the REST API app server didn't notice changes, so the properties didn't take effect. By going through the REST API, MarkLogic has a chance to do something with the properties.