MapGuide RFC 158 - Simplified JSON responses and GeoJSON support

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	12 Apr 2017
Last Modified	12 Apr 2017
Author	Jackie Ng
RFC Status	draft
Implementation Status	In Progress
Proposed Milestone	3.3
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This RFC proposes to simplify all JSON responses from the mapagent

Motivation

All JSON responses from the mapagent are verbatim conversions from their XML counterparts.

However this conversion process results in JSON that is quite cumbersome to consume:

• All properties are arrays.
• All properties are string values.

This is due to the conversion process not taking the content model (and its data types/element cardinality) into account, taking the lowest common denominator approach.

Proposed Solution

The MgJsonConvert class that does the actual XML to JSON conversion will be modified to include a hard-coded list of XML element paths:

• For elements that contain 0 to many elements
• For elements that are not string data types

During the conversion process, we check the computed XML element path of the element we're converting and check if it is in one of these two lists

• If it is in the first list, the element is written as a JSON array
• If it is in the second list, the element will not have its value quoted

To retain compatibility with clients using the JSON responses of the older mapagent, using simplified JSON responses is opt-in, by including CLEAN=1 as part of your mapagent request parameters. When this is specified, the old XML to JSON conversion behaviour will be used.

With the new JSON responses, not only are they more simpler to use (not everything is an array and not everything is a string and the content structure is semantically similar to their XML counterparts), but is also much more compact due to the amount of [ and " characters we save by not converting everything to string arrays

Fusion will also be updated to take advantage of the new clean JSON responses.

GeoJSON output

For the SELECTFEATURES mapagent operation, even with the clean JSON response formatting applied, the JSON response is still near-useless for consumption by client applications.

For this particular operation, if we want the response in JSON, since it includes spatial data for features it is more practical to return this in GeoJSON format, which is more ubiquitous and more practical for client-application consumption.

To enable this, we'll be adding a new MgGeoJsonWriter utility class to the PlatformBase library to enable easy GeoJSON conversion from feature readers

/////////////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief
/// A helper class to output GeoJSON from feature readers
///
class MG_PLATFORMBASE_API MgGeoJsonWriter : public MgGuardDisposable
{
PUBLISHED_API:
    //////////////////////////////////////////////////////////////////
    /// \brief
    /// Constructs a MgGeoJsonWriter object
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// MgGeoJsonWriter();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// MgGeoJsonWriter();
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// MgGeoJsonWriter();
    /// \htmlinclude SyntaxBottom.html
    ///
    MgGeoJsonWriter();

    //////////////////////////////////////////////////////////////////
    /// \brief
    /// Converts the current feature in the given feature reader to GeoJSON
    ///
    /// \remarks
    /// The id and geometry properties are inferred from the class definition returned by the feature reader
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// string FeatureToGeoJson(MgFeatureReader featureReader, MgTransform transform);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// String FeatureToGeoJson(MgFeatureReader featureReader, MgTransform transform);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// string FeatureToGeoJson(MgFeatureReader featureReader, MgTransform transform);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param featureReader (MgFeatureReader)
    /// The feature reader
    ///
    /// \param transform (MgTransform)
    /// An optional transform
    ///
    /// \return
    /// Returns the GeoJSON output as a string.
    ///
    STRING FeatureToGeoJson(MgFeatureReader* featureReader, MgTransform* transform);

    //////////////////////////////////////////////////////////////////
    /// \brief
    /// Converts the current feature in the given feature reader to GeoJSON
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// string FeatureToGeoJson(MgFeatureReader featureReader, MgTransform transform, string idPropertyName, string geomPropName);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// String FeatureToGeoJson(MgFeatureReader featureReader, MgTransform transform, String idPropertyName, String geomPropName);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// string FeatureToGeoJson(MgFeatureReader featureReader, MgTransform transform, string idPropertyName, string geomPropName);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param featureReader (MgFeatureReader)
    /// The feature reader
    ///
    /// \param transform (MgTransform)
    /// An optional transform
    ///
    /// \param idPropertyName (String/string)
    /// The name of the id property. The value of the property specified will be written to the top-level "id" property of the GeoJSON
    ///
    /// \param geomPropName (String/string)
    /// The name of the geometry property. The value of the property specified will be written to the top-level "geometry" property
    /// of the GeoJSON. If this property is not specified, no geometry is written.
    ///
    /// \return
    /// Returns the GeoJSON output as a string.
    ///
    STRING FeatureToGeoJson(MgReader* reader, MgTransform* transform, CREFSTRING idPropertyName, CREFSTRING geomPropName);
};

The SELECTFEATURES operation with CLEAN=1 will use this class to output the response as GeoJSON.

This class is also available to the public API for MapGuide applications to use.

Implications

Any time a new schema or schema revision is introduced, this hard-coded list will have to be updated to know which elements in these new schemas require special processing.

Test Plan

Test all applicable mapagent operations with CLEAN=1 to verify clean JSON output.

Funding / Resources

Community