# Mappedin Venue Format

Types and documentation for the Mappedin Venue Format.

## Usage
- Edit `src/index.d.ts` type declaration file.
- Generate documentation with `yarn docs`. They will be output in `docs/`.
  - Unfortunately the zod-schema inferred typescript do not expand so many of these docs are a bit terse.

## Versioning
- MVF v1 is described on a branch named `mvf-v1`. This is a protected branch like `master`, changes must be done via PR.
- `master` represents the currently evolving v2 spec.

## Deployment

- One day the typescript types and maybe the schema and validation functions will be published somewhere.

### What is the history of MVF?

Started as more of a business / political play, moreso than anything else
  - Apple was trying to get all the malls onboard with getting the data in their system with IMDF, named AVF at the time
  - Mappedin already had business relationships with all the top malls, so we tried to create a standard of "how you do indoor mapping data"
  - This standard was MVF

The standard was a byproduct of the result we were actually going for.  The result was getting apple to the negotiating table.  And getting some malls we were missing to talk to us.

So we _did_ develop a standard.  That became a common interface format that everything could produce or read, aspirationally.

We did a lot of work to come up with the standard, but there was no use case that allowed us to really test our assumptions

### Who are the stakeholders of MVF, internally?

- Internal MVF consumers
  - interested in a small bundle size
  - backwards compatibility: breaking existing SDK users is highly inconvenient
  - motivated by 3D rendering needs
  - ability to support advanced use cases like autopathing
- Integrations team, representing external users
  - interested in stability, documentation, and ease of use
  - standardization and ability to use standard tooling
  - engaged with external developers
  - also engaged with external business representatives
- Teams maintaining tools which generate MVF
  - concerned with how to produce MVF with the data we have
  - is MVF close to standard geojson
- Product representing external Customers and Prospective Customers who rely on MVF
  - Will my custom use case be supported?  Specific fields in MVF
  - engaged in sales and retention conversations

### Why MVF? What are the goals of MVF?

- Primary use case: we need a way for people who don't want to use our rendering engine, to use our data
- We need the data to be decoupled from the specific API / API implementation
- users should understand what version of MVF they have (SMVF vs MVF)
- MVF should be extensible with additive only files/data

- MVF is geojson compliant
- Rendering the map in 3D in the SDK
- 2D custom rendering, rendered by 3rd party tools
- simple 3D custom rendering, rendered by 3rd party tools using included style data
- navigation in 3rd party applications
- rendering small venues (non-chunked bundle size is reasonable)
- representing multiple buildings on a campus or city block
- outdoor features within the extents of a property
- arbitrary 3d models on a styled version of the map
- supporting aesthetically-transformed versions of the MVF (currently SMVF, "styled mvf")
- we should be able to represent location and category data
- caching and offline-usage

Future goals:
- autopathing in the SDK
  - obstructions, enterable spaces, and walkable areas
- entrances, specifically with opening-hours
- localization: get an MVF in one of multiple languages
- rendering large venues resulting in bundles that are too large
- ingest data to mappedin ecosystem: can non-mappedin entities produce MVF data that we import
- mapping out all 100k electrical outlets in your airport?
- support for multiple style themes in one bundle?  Day and night theme?
- events? (as an extension)?
- linking external data-sources to entities (like locations) within the MVF
  - external IDs?
- maybe a manifest-with-url's API, in addition to zip-file API

### What are non-goals of MVF?

A non-exhaustive list of examples:
- ability to construct the building
- instructions for installation of electrical wiring
- accurate tree reproductions
- some data should not be in MVF.  Eg inventory is probably too transient and doesn't count as part of the venue

### What is MVF

The "what" is defined by the schema.  The schema is new and does not yet exhaustively constrain what meets the MVF requirements.  For example some string fields will be constrained by regex patterns, but the schema doesn't enforce this yet.

The schema is in the `src/schema` directory in this repo.

##### Coming in MVFV2
- points are rounded to 8 lnglat decimal places (enough to draw detailed things)

### What are MVF Extensions?

MVF Extensions are purely-additive files in the MVF enabling additional use cases.

An extension must not require adding fields to anything in MVF core, eg if you're adding a "funkyStyles" extension, you cannot add your funkyStyleId to MVF spaces.  Instead, have your funkyStyle specify the spaces by ID that it applies to.

MVF extensions are defined in the `src/schema/extensions` directory.

### What assumptions do I need to make when consuming MVF?

- spaces are walkable
- obstructions are not walkable
- obstructions take precedence over spaces
- no more than 5 decimal points of accuracy in MVF even if the data contains more precision
  - precision lets you draw detailed things, but that doesn't imply global position accuracy
  - 5 decimal points is close to 1m, but varies based on global position
- MVF positions do not account for plate tectonics

### How is the spec evolved or expanded?  Proposal Process?

- Create a pull request against the `mvf` repo, editing the schema to reflect your proposal.
- If your change is an extension, do not edit any of the core schema files
  - Feel free to create a new file in `src/schema/extensions`
- Export the schema-derived type declarations in index.d.ts
- Edit the documentation in this README if appropriate