geojson: more comments and examples about extra/foreign members

Author: paulmach

geojson/example_test.go

@@ -43,9 +43,62 @@ func ExampleFeatureCollection_foreignMembers() {
 
 	fmt.Println(fc.Features[0].Geometry)
 	fmt.Println(fc.ExtraMembers["title"])
+
+	data, _ := json.Marshal(fc)
+	fmt.Println(string(data))
+
 	// Output:
 	// [102 0.5]
 	// Title as Foreign Member
+	// {"features":[{"type":"Feature","geometry":{"type":"Point","coordinates":[102,0.5]},"properties":{"prop0":"value0"}}],"title":"Title as Foreign Member","type":"FeatureCollection"}
+}
+
+// MyFeatureCollection is a depricated/no longer supported way to extract
+// foreign/extra members from a feature collection. Now an UnmarshalJSON
+// method, like below, is required for it to work.
+type MyFeatureCollection struct {
+	geojson.FeatureCollection
+	Title string `json:"title"`
+}
+
+// UnmarshalJSON implemented as below is now required for the extra members
+// to be decoded directly into the type.
+func (fc *MyFeatureCollection) UnmarshalJSON(data []byte) error {
+	err := json.Unmarshal(data, &fc.FeatureCollection)
+	if err != nil {
+		return err
+	}
+
+	fc.Title = fc.ExtraMembers.MustString("title", "")
+	return nil
+}
+
+func ExampleFeatureCollection_foreignMembersCustom() {
+	// Note: this approach to handling foreign/extra members requires
+	// implementing an `UnmarshalJSON` method on the new type.
+	// See MyFeatureCollection type and its UnmarshalJSON function above.
+
+	rawJSON := []byte(`
+	  { "type": "FeatureCollection",
+	    "features": [
+	      { "type": "Feature",
+	        "geometry": {"type": "Point", "coordinates": [102.0, 0.5]},
+	        "properties": {"prop0": "value0"}
+	      }
+	    ],
+	    "title": "Title as Foreign Member"
+	  }`)
+
+	fc := &MyFeatureCollection{}
+	json.Unmarshal(rawJSON, &fc)
+
+	fmt.Println(fc.FeatureCollection.Features[0].Geometry)
+	fmt.Println(fc.Features[0].Geometry)
+	fmt.Println(fc.Title)
+	// Output:
+	// [102 0.5]
+	// [102 0.5]
+	// Title as Foreign Member
 }
 
 func ExampleUnmarshalFeatureCollection() {

geojson/feature_collection.go

@@ -20,7 +20,8 @@ type FeatureCollection struct {
 	Features []*Feature `json:"features"`
 
 	// ExtraMembers can be used to encoded/decode extra key/members in
-	// the base of the feature collection.
+	// the base of the feature collection. Note that keys of "type", "bbox"
+	// and "features" will not work as those are reserved by the GeoJSON spec.
 	ExtraMembers Properties `json:"-"`
 }
 
@@ -41,6 +42,8 @@ func (fc *FeatureCollection) Append(feature *Feature) *FeatureCollection {
 // MarshalJSON converts the feature collection object into the proper JSON.
 // It will handle the encoding of all the child features and geometries.
 // Alternately one can call json.Marshal(fc) directly for the same result.
+// Items in the ExtraMembers map will be included in the base of the
+// feature collection object.
 func (fc FeatureCollection) MarshalJSON() ([]byte, error) {
 	var tmp map[string]interface{}
 	if fc.ExtraMembers != nil {
@@ -50,6 +53,7 @@ func (fc FeatureCollection) MarshalJSON() ([]byte, error) {
 	}
 
 	tmp["type"] = featureCollection
+	delete(tmp, "bbox")
 	if fc.BBox != nil {
 		tmp["bbox"] = fc.BBox
 	}
@@ -63,6 +67,7 @@ func (fc FeatureCollection) MarshalJSON() ([]byte, error) {
 }
 
 // UnmarshalJSON decodes the data into a GeoJSON feature collection.
+// Extra/foreign members will be put into the `ExtraMembers` attribute.
 func (fc *FeatureCollection) UnmarshalJSON(data []byte) error {
 	tmp := make(map[string]json.RawMessage, 4)