Geo SVG

Draft 001

A bidriectional (geo)json <-> (geo)svg system

by: syonfoxx created: 27/05/2024

Version 1

0.0 Motivation / Introduction

Web mapping encompasses numerous standards, but as we approach client devices and end-users, the complexity of implementation explodes. There are many standards and intricate details to consider.

Generally, I applaud standards for their ability to consolidate focus and guide collective action toward more consistent and reusable solutions.

Two standards that have gained widespread adoption are GeoJSON and SVG.

This proposal aims to consolidate an interchange between the two formats, allowing interactive maps to be transferred in a single file. It also aims to leverage existing technology and infrastructure to provide a system that is easy to adopt for both web and GIS professionals.

1.0 Specifying Geo SVG Version

A Geo SVG MAY contain the root tag attribute (this is recommended):

xmlns:geo="https://sgol.pub/geosvg"

It may also contain a version tag: geo:version="1.0"

Additionally, it may contain a metadata tag denoting the GeoSVG version:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:geo="https://sgol.pub/geosvg">
    <metadata>
        <geo:version>1.0</geo:version>
    </metadata>
    <!--...-->
</svg>

Note: Although this is merely a recommendation, as Geo SVG shall be detectable by searching paths for valid GeoJSON metadata tags, it is advised to follow this simple spec for ease of implementation. My recommendation is to include the xmlns:geo tag.

2.0 Geo SVG Specification Requirements

These are the rules for if this then that style requirments. generaly GeoSVG conforms to the SVG spec; whithout adding aditional tags etc.

2.1 Encoding GeoJSon Data In Svg

Any path that is a valid geospatial feature SHALL contain a desc tag of valid GeoJSON feature: RFC 7946 Section 3.2. Note: it is the encoders descresion whitch features are valid

any geo svg desc tag MUST contain the css class=geo-json-feature and hear-withing it SHALL have valid geoJSON feature string.

Alternitivaly this chould be stated as. IF an path like svg element contains a desc tag of class geo-json-feature then it MUST contain a valid GeoJSON feature.

	let svg; // get your svg into the dom how you see fit.
	
	let featuresMeta = Array.from(svg.querySelectorAll("desc.geo-json-feature"))
	
	try {
	let features = featuresMeta.map(fel=>{
    	return JSON.parse(fel.innerText);
    	//todo catch errors but if valid there sould not be any.
	})
	
	let geoJson = {
    	type: "FeatureCollection",
    	features
	}
	} catch (e) {
		throw "This GeoSVG violates spec 2.1 of https://sgol.pub/geo_svg#2.0-geo-svg-specification-requirements"
	}

3.0 Geo SVG Specification Recommendations.

These are recomendations for creating a beutiful GeoSVG.

3.1

It is recommend to also include a title tag for supported renderers to provide a tooltip on each feature.

Note as per the SVG spec this should be the first child of a path like tag.

let path = svg.querySelector(".your_id_or_class_or_somthing");

let name = "Foo Bar";
let str  = `<title>${name}<title>${path.innerHTML}`;
path.innerHTML = str;

This title with show as a tooltip on hover in the svg whitch is a nice effect.

3.1.1

You may want to add hover efects to your svg. It is recomended to add these programaticaly in your aplication for group selections you may want to add clases to this title tag as custom metadata. I would advise that rather you ad classes directly to the path like element.

3.2

It is recommended to provide an id for each feature prefaced with an f character.

path.id="f"+your_custom_id_implementation

Refrence Implementation: `https://freemap.online/js/geosvg/GeoSvgIdUtil.js`

3.2.1 Introduction

This specification defines the encoding and decoding of XML IDs for use in GeoSVG documents. These IDs are designed to be unique, URL-safe, and capable of embedding multiple data elements.

3.2.2 XML ID Encoding Rules

1. Prefix: All IDs must start with the prefix f.
2. Character Replacement: The following characters are replaced to ensure compatibility with XML ID rules:
   • ! is replaced with %21
   • ' is replaced with %27
   • ( is replaced with %28
   • ) is replaced with %29
   • * is replaced with %2A
   • ~ is replaced with %7E
3. Percent Encoding: Any remaining invalid XML ID characters are percent-encoded using encodeURIComponent
4. Then all % is replaced with : to comform to valid xmlid chars.

This encoding proccess ensure that all special chars are converted to valid xml id chars. recomended signitures:

function encodeXmlId(s: string): string
function decodeXmlId(s: string): string
//optional 
function validateXmlId(id: string): boolean

3.2.3 GeoSvgIdUtils

1. Delimiter: The $ character is used to separate data elements within the ID. First all existing dleinators are replaced with their encoded versions
   • ie args = args.map(arg=>{return arg.replaceAll("$", ":24")});
2. Joining: Then all encoded arguments are joined with the deleminator
   • ie let s = args.join("$");
3. encodXMLId Finaly the above string encoding process is used to encode all other character to valid xml id chars.
   • ie return encodeXmlId(s);

3.2.4 GeoSvgIdUtil Class

class GeoSvgIdUtil {
	encodeId(...args)) -> s;  			//Decodes a GeoSVG ID into its original data elements.
	decodeId(s: string) -> [...args];	
	constructor(delimiter="$");
}

• delimiter (string): Character used to separate data elements in the ID. Defaults to $.
• args (string[]): Data elements to encode.
• s: The encoded XML ID.

Example Usage

let util = new GeoSvgIdUtil();
let encodedId = util.encodeId("data1", "data2", "data3");
let decodedData = util.decodeId(encodedId);

3.2.5 Overview

This specification ensures that XML IDs used in GeoSVG documents are valid, unique, and capable of containing multiple pieces of data in a standardized format. By following these encoding and decoding rules, GeoSVG IDs maintain compatibility with XML standards while allowing for flexible and structured data embedding.

it is recommended to include 1 or more most useful data attributes joined with $ separator

Note first we replace existing denominators with urlencoded deliminator (replace % with :)

Then we join all arguments with the deliminator and urlencode

Fianly we replace all non XML id characters with their corasponding equivalent.

Most notably we replace % with : AFTER replacing all other specal characters with their %XX equivalent

3.3

// The ID is valid if it passes all checks
return true;

}

Prior Works

" Life obliges me to do something, so I paint. ” - Rene Magritte

https://web.archive.org/web/20080116142201/https://www.gis-news.de/svg/map2svg.htm#literature

Notibaly the above lists cordanate representation etc as future developments.