From XML to JSON: database definitions in settings

Wiki (nl)
,
1

Go to English version

From release 27.0, Invantive UniversalSQL reads database definitions from settings*.json instead of from settings*.xml. Existing XML files are automatically migrated.

Support for the XML format will no longer be available from Invantive UniversalSQL release 28.0 (scheduled for early 2028).

Why

The XML format dates back to 2009 and has two issues that are resolved by changing formats.

  • Tooling: reading or generating settings requires XPath and/or XSLT. However, most programming languages can parse JSON without additional libraries. Generating a settings file per customer or environment thus becomes a matter of text templates rather than XML templates.
  • Outdated elements: the XML format carries a lot of historical baggage regarding concepts around database connections. Many elements are no longer supported or relevant. The JSON format uses current concepts, so what you read is exactly what the term means.

Format

The settings*.json format closely resembles the XML format. The main changes are:

  • <connection> is called database (singular) or databases (plural).
  • <database> is called dataContainer (singular) or dataContainers (plural).

For example:

{ "version": "5"
, "groups":
  [ { "name": "ACME"
    , "sortingOrder": 100
    , "databases":
      [ { "name": "acme-eol"
        , "shortDescription": "Exact Online"
        , "sortingOrder": 10
        , "authentication": "Default"
        , "dataContainers":
          [ { "kind": "dataContainer"
            , "provider": "ExactOnlineAll"
            , "alias": "eol"
            , "order": 10
            , "connectionString": "..."
            }
          ]
        }
      ]
    }
  ]
}

Comments and trailing commas are skipped when a file is read. Comments and trailing commas disappear if a product should rewrite the settings*json file.

Migration

An effort has been made to make migration as simple as possible.

The first time a product from release 27.0 reads a settings*.xml file for which no .json file with the same name exists, it will create a functionally identical JSON file next to the XML file. The XML file remains unchanged. Outdated properties are ignored.

Files created by the automatic discovery process (settings-discovery*.xml) are never migrated since they are tied to a specific major release.

Which Format is Used?

Version Behaviour
26.0 and earlier settings*.xml is used; a settings*.json file is ignored.
26.1 (BETA of 27.0) settings*.json is used; a settings*.xml with the same name is ignored and used to create the JSON variant.
27.0 settings*.json is used; a settings*.xml with the same name is ignored and used to create the JSON variant.
28.0 settings*.json is used; the XML format is no longer supported or used to generate the JSON variant.

When an environment only uses release 27.0 or later, all settings*.xml files can be safely removed if the file is available in JSON format.

From XML to JSON: database definitions in settings*