openskidata-format 0.14.0 → 1.0.0

package/src/SkiArea.ts

@@ -1,11 +1,30 @@
-import { Activity } from './Activity'
 import { FeatureType } from './FeatureType'
 import { LiftType } from './Lift'
 import { Location } from './Location'
-import { RunConvention, RunDifficulty } from './Run'
-import Source from './Source'
+import { RunDifficulty, RunDifficultyConvention } from './Run'
+import { Source } from './Source'
 import { Status } from './Status'
 
+/**
+ * A ski area feature is derived from several sources:
+ * - OpenStreetMap site=piste relations
+ * - OpenStreetMap landuse=winter_sports areas that contains ski runs
+ * - Skimap.org ski areas
+ *
+ * The processor attempts to merge the data of all sources to create a single ski area feature.
+ *
+ * In some cases merging may fail and duplicate ski areas will be produced. This is likely due to ambiguous data.
+ * Check:
+ * - that a site=piste relation contains all the lifts/runs. If many lifts/runs are missing, merging will fail.
+ * - that if there are multiple landuse=winter_sports areas representing a single ski area. In this case a multipolygon relation should be used.
+ * - that if there are multiple Skimap.org ski areas representing a single ski area.
+ *
+ * General recommendation for ski area tagging in OpenStreetMap:
+ * - start with a landuse=winter_sports area as it's easy to set up and maintain.
+ * - if that's not explicit enough, add a site=piste relation as well.
+ *
+ * Note: if runs are present but there is no associated ski area source, a ski area feature is generated with no name and no source.
+ */
 export type SkiAreaFeature = GeoJSON.Feature<SkiAreaGeometry, SkiAreaProperties>
 
 export type SkiAreaGeometry =
@@ -13,42 +32,69 @@ export type SkiAreaGeometry =
   | GeoJSON.Polygon
   | GeoJSON.MultiPolygon
 
-export interface SkiAreaProperties {
+export type SkiAreaSummaryFeature = GeoJSON.Feature<
+  SkiAreaGeometry,
+  SkiAreaSummaryProperties
+>
+
+/**
+ * @property {string} id - Unique identifier for the ski area. The ID is just a hash of the feature, so will change if the feature changes in any way. If a stable identifier is needed, use the wikidata_id property, or a source id.
+ * @property {string | null} name - Name of the ski area.
+ * @property {Source[]} sources - Data sources.
+ * @property {SkiAreaActivity[]} activities - Activities available at this ski area, derived from presence of ski runs and Skimap.org data.
+ * @property {SkiAreaStatistics} statistics - Statistics generated from associated runs / lifts.
+ * @property {Status | null} status - Operational status. Derived from OpenStreetMap lifecycle tags and Skimap.org data.
+ * @property {RunColorConvention} runConvention - Color convention used for runs at this ski area.
+ * @property {string[]} websites - Official website(s) of the ski area. Derived from the OpenStreetMap website tag and Skimap.org data.
+ * @property {string | null} wikidata_id - Wikidata identifier. Derived from the OpenStreetMap wikidata tag.
+ * @property {Location | null} location - Reverse geocoded country / region information.
+ */
+export type SkiAreaProperties = SkiAreaSummaryProperties & {
+  sources: Source[]
+  statistics?: SkiAreaStatistics
+  runConvention: RunDifficultyConvention
+  websites: string[]
+  wikidata_id: string | null
+}
+
+export type SkiAreaSummaryProperties = {
   type: FeatureType.SkiArea
   id: string
   name: string | null
-  sources: Source[]
-  activities: Activity[]
-  generated: boolean
-  statistics?: SkiAreaStatistics
+  activities: SkiAreaActivity[]
   status: Status | null
-  runConvention: RunConvention
-  websites: string[]
   location: Location | null
 }
 
-export interface SkiAreaStatistics {
+export enum SkiAreaActivity {
+  Downhill = 'downhill',
+  Nordic = 'nordic',
+}
+
+export type SkiAreaStatistics = {
   runs: RunStatistics
   lifts: LiftStatistics
   minElevation?: number
   maxElevation?: number
 }
 
-export interface RunStatistics {
+export type RunStatistics = {
   minElevation?: number
   maxElevation?: number
   byActivity: RunStatisticsByActivityAndDifficulty
 }
 
 export type RunStatisticsByActivityAndDifficulty = {
-  [key in Activity | 'other']?: { byDifficulty: RunStatisticsByDifficulty }
+  [key in SkiAreaActivity | 'other']?: {
+    byDifficulty: RunStatisticsByDifficulty
+  }
 }
 
 export type RunStatisticsByDifficulty = {
   [key in RunDifficulty | 'other']?: { count: number; lengthInKm: number }
 }
 
-export interface LiftStatistics {
+export type LiftStatistics = {
   minElevation?: number
   maxElevation?: number
   byType: LiftStatisticsByType
@@ -59,11 +105,3 @@ export type LiftStatisticsByTypeKey = LiftType | 'other'
 export type LiftStatisticsByType = {
   [key in LiftStatisticsByTypeKey]?: { count: number; lengthInKm: number }
 }
-
-export interface MapObjectStatistics {
-  count: number
-  lengthInKm: number
-  minElevation?: number
-  maxElevation?: number
-  combinedElevationChange?: number
-}

package/src/Source.ts

@@ -3,7 +3,7 @@ export enum SourceType {
   OPENSTREETMAP = 'openstreetmap',
 }
 
-export default interface Source {
+export type Source = {
   type: SourceType
   id: string
 }

package/src/Status.ts

@@ -1,3 +1,15 @@
+/**
+ * Status of a feature.
+ *
+ * Note that this is not real-time status but indicates whether a feature is in operation when conditions permit or is abandoned, etc.
+ *
+ * Primarily derived from OpenStreetMap tags.
+ * Additionally, Skimap.org data provides status information for ski area features only.
+ *
+ * Tagging schemes supported are:
+ * - lifecycle prefixes (preferred) https://wiki.openstreetmap.org/wiki/Lifecycle_prefix
+ * - separate lifecycle tags ("proposed=yes", etc)
+ */
 export enum Status {
   Operating = 'operating',
   Disused = 'disused',

package/src/index.ts

@@ -1,4 +1,3 @@
-export * from './Activity'
 export * from './ElevationProfile'
 export * from './FeatureType'
 export * from './Lift'

package/src/util/exhaustiveMatchingGuard.ts

@@ -0,0 +1,3 @@
+export const exhaustiveMatchingGuard = (value: never): never => {
+  throw new Error(`Unhandled case: ${value}`)
+}

package/dist/Activity.d.ts

@@ -1,5 +0,0 @@
-export declare enum Activity {
-    Downhill = "downhill",
-    Nordic = "nordic",
-    Backcountry = "backcountry"
-}

package/dist/Activity.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Activity = void 0;
-var Activity;
-(function (Activity) {
-    Activity["Downhill"] = "downhill";
-    Activity["Nordic"] = "nordic";
-    Activity["Backcountry"] = "backcountry";
-})(Activity || (exports.Activity = Activity = {}));
-//# sourceMappingURL=Activity.js.map

package/dist/Activity.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Activity.js","sourceRoot":"","sources":["../src/Activity.ts"],"names":[],"mappings":";;;AAAA,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,iCAAqB,CAAA;IACrB,6BAAiB,CAAA;IACjB,uCAA2B,CAAA;AAC7B,CAAC,EAJW,QAAQ,wBAAR,QAAQ,QAInB"}

package/src/Activity.ts

@@ -1,5 +0,0 @@
-export enum Activity {
-  Downhill = 'downhill',
-  Nordic = 'nordic',
-  Backcountry = 'backcountry',
-}