Metadata schema for atlascope‐v2

An Atlascope instance represents the configuration necessary for a single Atlascope installation to initialize itself. The instance metadata is located in the required file /src/config/instance.json.

The instance.json file depends on a historic layers footprints file, which points to spatial metadata used to load atlas layers.

Finally, the historicLayersFootprintsFile points to individual TileJSON files that contain a field for the XYZ tiles where atlas layers are hosted.

Configuring instance.json metadata file

All of these keys are required components of the instance.json file except for coverageDescriptiveList.

An example instance.json file can be found here: https://github.com/bplmaps/atlascope-v2/blob/main/src/config/instance.json

Key	Type	Description
name	String	Name of host city
tagline	String	Tagline for instance
geographicCoverage	String	Common language description of area covered
institutionalShortName	String	Maintaining institution name
institutionalCredit	String	Common language institutional credit
defaultStartLocation	Object	Object that configures starting location
historicLayersFootprintsFile	String (URL)	Fully-qualified URL to a GeoJSON file with the extents of each historic layer
referenceLayers	Array	Array defining base layers for initialization
baseURL	String (URL)	Base URL of the deployed instance
coverageDescriptiveList	Array	Optional array for places of interest, stored as an object with keys of name and center

defaultStartLocation

Key	Type	Description
name	String	Common language start name
center	Array	Center of start location
zoom	Integer	Zoom level
overlayLayerId	String	id of atlas overlay for initialization
baseLayerId	String	id of base map for initialization

referenceLayers

An example array for the referenceLayers value can be found here: https://github.com/bplmaps/atlascope-v2/blob/main/src/config/instance.json#L25

Required properties of historic layers footprints file

The key historicLayersFootprintsFile must have a value of a GeoJSON file endpoint consisting of Polygon or MultiPolygon objects, each of which should be the outer extent of a single atlas layer’s coverage. Each object should have the following properties

Key	Type	Required	Description
identifier	String	Yes	A unique, opaque identifier for the layer
publisherShort	String	No	A truncated version of the publisher
year	Integer	Yes	Year which is primarily depicted by atlas layer
bibliographicEntry	String (Markdown)	No	Full bibliographic entry in the preferred format, in Markdown
source	Object	Yes	Link to the map source as an object with keys type and url
catalogPermalink	String (URL)	No	Permalink to the catalog record
heldBy	Array	No	Array of text names of institution/s holding the map
plateGeometryFile	String (URL)	No	Link to a file containing information about geometry and name for each plate within the atlas
fallbackTitle	String	No	Optional fallback title if not using year as the listing in the drop-down menu
fallbackSubtitle	String	No	Optional fallback subtitle if not using publisherShort as the subtitle in the drop-down menu
sponsors	Array	No	Array of sponsors for the map, stored as object with keys name and url

This file should be saved as {name}-volume-extents.geojson; e.g., in Atlascope Boston, the historic layers footprints file is saved as boston-volume-extents.geojson.

An example historicLayersFootprintsFile can be found here: https://s3.us-east-2.wasabisys.com/urbanatlases/extents/boston-volume-extents.geojson

source object values

The key source of historicLayersFootprintsFile must have a value of an object containing at least the type and url keys as described below:

Key	Type	Required	Description	Example Value
type	String	Yes	One of "tilejson", "xyz"	"tilejson"
url	String	Yes	URL endpoint	"https://s3.us-east-2.wasabisys.com/urbanatlases/als97ccxx/tileset.json"
hidden	Boolean	No	???	No

tileset.json file

The historic footprints layers file loads atlas layers as XYZ tiles through individual TileJSON files (usually saved as tileset.json). Atlascope Boston follows the TileJSON 2.2.0 specification.

An example TileJSON formatted for Atlascope can be found here: https://s3.us-east-2.wasabisys.com/urbanatlases/al7rtfm98/tileset.json

Key	Type	Required	Description
tilejson	String	Yes	The version of the TileJSON specification used
name	String	Yes	The name of the layer
description	String	Yes	A string value describing the layer
version	String	Yes	The version number of the layer
attribution	String	Yes	Attribution information
scheme	String	Yes	A string value indicating the tile scheme used (e.g., "xyz")
tiles	Array	Yes	An array containing the XYZ tile endpoint of this layer
data	Array	Yes	An array containing the endpoint of the plates.geojson file
minzoom	Integer	Yes	The minimum zoom level at which this layer is available
maxzoom	Integer	Yes	The maximum zoom level at which this layer is available
bounds	Array	Yes	An array containing bounding box lat/long derived from plates.geojson file

Plate extents file

Each atlas should also have its own plates.geojson (typically saved somewhere in the same Wasabi directory, and linked to from the plateGeometryFile property in the footprints file) that describes the geometry of each plate, and information about the plate. Usually this can be the very same "topology" file which is used during the georeferencing process. It should contain Polygons or MultiPolygons, each of which describes the boundaries of a single plate, and with the following properties

Key	Type	Required	Description
identifier	String	Yes	Suffixed from the identifier key of the entire atlas. e.g., ark:/50959/tt44pv907/26 or ark:/50959/tt44pv907/26a
name	String	Yes	Human-readable plate name, e.g., "Plate 26"
imageUri	String	No	Stable IIIF Image API identifier for this item
allmapsMapID	String	No	Allmaps map ID
digitalCollectionsPermalinkPlate	String	No	URI to the plate in digital collections if available at the plate level

An example plate extents file can be downloaded here: https://s3.us-east-2.wasabisys.com/urbanatlases/als97ccxx/plates.geojson"

identifier required string: Suffixed from the identifier key of the entire atlas. For instance, if the identifier required string: for the atlas was ark:/50959/tt44pv907, then plate 26 could be ark:/50959/tt44pv907/26

• For plates containing multiple maps, the suffix will follow a numbering convention in which individuals numbers are suffixed with, e.g., ../1a, ../1b
• Letters should be assigned alphabetically from left to right, according to the order in which maps appear on an atlas plate

name required string: human readable plate name, e.g. “Plate 26”

imageUri string: stable IIIF Image API identifier for this item (e.g., https://iiif.digitalcommonwealth.org/iiif/2/commonwealth:1r66mq13h)

allmapsMapID string: Allmaps map ID

digitalCollectionsPermalinkPlate string: if available at the plate level, URI to the plate in digital collections