From XML to JSON: database definitions in settings*

Wiki (en)
,
1

Go to Dutch version

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

Support for the XML format is no longer available from Invantive UniversalSQL release 28.0 (scheduled for release around start of 2028).

Why

The XML format dates from 2009 and carries two problems that a format change resolves.

  • Tooling: reading or generating a settings requires XPath and/or XSLT. However, most languages parse JSON without additional libraries. Generating a settings file per customer or per environment becomes a text templating exercise rather than an XML one.
  • Obsolete elements: the XML format has carries a lot of history on the database connectivity concepts. Many elements are no longer supported or relevant. The JSON format uses the current concepts, so what you read is what the term means.

Format

The settings*.json format strongly resembles the XML format. The most important changes are:

  • <connection> is termed database (singular) or databases (plural).
  • <database> is termed 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 tolerated when a file is read. Comments and trailing commas disappear if a product rewrites the settings*json file.

Migration

An effort has been made to make the migration as easy as possible.

The first time a release 27.0 product reads a settings*.xml file for which no identical named .json file exists, it creates that functionally identical JSON file next to it. The XML file is left unchanged. Obsoleted properties are ignored.

Files produced by automatic discovery (settings-discovery*.xml) are never migrated since they are associated with a specific major release.

Which Format is Used

Release 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; an identical named settings*.xml is ignored and used to create the JSON variant.
27.0 settings*.json is used; an identical named settings*.xml 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 create the JSON variant.

When an environment only uses release 27.0 or newer, all settings*.xml files can safely be removed when the JSON format file exists.