WebMap JSON Compatibility Contract

This document defines the compatibility contract for parseWebMap() in @honua/sdk-js/webmap.

Version target: ArcGIS WebMap JSON 2.x (current AGOL output).

Output Contract

parseWebMap(input) returns:

style: Honua/MapLibre style specification (version: 8)
warnings: non-fatal compatibility warnings (code, path, message, optional context)
bookmarks: passthrough WebMap bookmarks array
popups: popup metadata keyed by operational layer id

Parser behavior:

Unsupported or unknown properties are warnings, not throw conditions.
Conversion aims to preserve visible map behavior for supported 2D properties.
Unsupported 3D and complex Arcade flows are explicitly called out for manual intervention.
The exploratory Cesium example under docs/examples/cesium-route-playback/ consumes HonuaClient.queryFeatures() directly and does not expand parseWebMap() 3D support.

WebMap JSON area	Support	Notes
`operationalLayers`	Partial	`ArcGISFeatureLayer` and `ArcGISMapServiceLayer` supported
`baseMap`	Partial	Tiled basemap layers supported; vector basemap partial
`spatialReference`	Partial	Web Mercator (3857/102100/102113) and 4326 handling
`initialViewpoint`	Partial	`targetGeometry` point/extent + optional `scale`
`initialExtent`	Full	Converted to `center`/`zoom`
`bookmarks`	Full	Passed through in parser result
Simple renderer	Full	Converted to layer paint/layout
Unique value renderer	Full	Converted to `match` expressions
Class breaks renderer	Full	Converted to `step` expressions
Heatmap renderer	Unsupported	Warning emitted
Dot density renderer	Unsupported	Warning emitted
Popup `title`/`description`	Full	Preserved in popup config
Popup `fieldInfos`	Full	Preserved in popup config
Popup `mediaInfos`	Full (basic)	Preserved in popup config
Popup `expressionInfos`	Unsupported	Warning emitted; manual intervention
`labelingInfo`	Partial	Basic `$feature.FIELD` and simple concat only
3D properties	Unsupported	Warning emitted; manual intervention

Primary warning codes emitted by the parser:

Golden fixtures live under:

Fixture suite test:

The suite is executed by npm test, which is required in CI (.github/workflows/ci.yml) on every PR and push to trunk.

Manual intervention is expected for: