Map Versioning and Release Management

Map data changes over time.

Robotics platforms often need to publish new versions of the same map product as roads change, delivery zones expand, lane geometry improves, validation pipelines evolve, or operational requirements change. At the same time, older versions may still need to remain discoverable for auditing, debugging, reproducibility, or historical analysis.

Geoportal can act as a release management system for map data products by using versioned Portal Objects and Portal Links.

Guide Overview

A map release is represented as a versioned Portal Object.

All examples in this guide use Portal Items, but the same versioning model can also be applied to Portal Collections as well.

Portal Objects are connected to each other with Portal Links. Each link includes a rel value that describes the relationship between the current object and the linked object.

For map versioning, Geoportal uses the following link versioning relation types:

Relation type	Purpose
`self`	Points to the current Portal Object.
`latest-version`	Points from an older Portal Object to the current latest version.
`predecessor-version`	Points from a newer Portal Object to the previous version.
`successor-version`	Points from an older Portal Object to the next version.
`version-history`	Points to a changelog, release notes document, or structured version history resource.

These links allow clients to navigate a linear version history while still preserving older releases.

Core concepts

Portal Object

A Portal Object is any entity in Geoportal. This can be a Portal Item, Portal Collection, Portal Catalog, Portal Asset, or Portal Link.

A Portal Object may represent many different things. For the sake of this guide, we will assume that by Portal Object, we mean a Portal Item.

In most map release workflows, each new version of a map product is represented as a new Portal Object.

Version Lineage

A version lineage is the ordered chain of releases for a map product.

For this guide, Geoportal assumes a linear release history:

`v1.0.0` -> `v1.1.0` -> `v1.2.0`

Each release has at most one immediate predecessor and at most one immediate successor.

This keeps the release model simple for clients. A client can start from any version and navigate backward or forward through the release history using predecessor-version and successor-version links.

flowchart LR
    subgraph Lineage["Version Lineage"]
        direction LR
        V100["v1.0.0"]
        V110["v1.1.0"]
        V111["v1.1.1<br/>(latest)"]
    end

    V100 -->|successor-version| V110
    V110 -->|successor-version| V111

    V111 -->|predecessor-version| V110
    V110 -->|predecessor-version| V100

    V100 -. "latest-version" .-> V111
    V110 -. "latest-version" .-> V111

Latest Version

The latest version is the version that new consumers should use by default.

Older Portal Objects should link to the latest version using latest-version.

The latest Portal Object does need a latest-version link to itself. Every Portal Object should also have a self link that identifies its own canonical URL.

Version History

A version history is a human-readable or machine-readable changelog for a map product.

A Portal Object can link to its version history using the version-history relation type.

The linked resource may be a Markdown file, a JSON document, a Portal Object, or another resource type supported by your organization.

For example, a version-history link may point to a Markdown file:

{
  "href": "https://www.lateral-robotics.com/portal/items/01234567-89ab-cdef-0123-456789abcdef/version-history.md",
  "rel": "version-history",
  "title": "Map Version History",
  "type": "text/markdown"
}

Deprecated Version

A deprecated version is a version that remains available for reference, but should no longer be used for new work.

Deprecated versions should remain part of the version lineage. This allows users and systems to understand what happened historically, even if a specific release is no longer recommended.

A deprecated Portal Object should set deprecated to true.

If there is a newer version that should be used instead, the deprecated Portal Object should also include a successor-version link pointing to the current successor version, as well as a latest-version link pointing to the current latest version.

Standard Release Workflow

The standard release workflow is used when publishing a new version of an existing map product.

For example, suppose v1.0.0 is the current version of a map product and the client wants to publish v1.0.1.

The workflow is:

Create a new Portal Object for v1.0.1.
Add a self link to the new Portal Object.
Add a latest-version link to the new Portal Object that points to itself.
Add a predecessor-version link from v1.0.1 to v1.0.0.
Add a version-history link to the new Portal Object for v1.0.1.
Add a changelog entry to the version history for v1.0.1.
Add a successor-version link from v1.0.0 to v1.0.1.
Update all the latest-version links on predecessor objects so they point to v1.0.1.

sequenceDiagram
    actor Client
    participant Old as Portal Element v1.0.0
    participant New as Portal Element v1.1.0
    participant VH as Version History

    Client->>New: Create new Portal Element
    Client->>New: Add self link
    Client->>New: Add predecessor-version -> v1.0.0
    Client->>New: Add version-history link

    Client->>VH: Add changelog entry for v1.1.0

    Client->>Old: Add successor-version -> v1.1.0
    Client->>Old: Update latest-version -> v1.1.0

    Note over Old,New: v1.1.0 is now the latest version

After this workflow, clients can navigate:

from v1.0.1 back to v1.0.0 using predecessor-version
from v1.0.0 forward to v1.0.1 using successor-version
from older versions directly to v1.0.1 using latest-version

Examples

Publishing a New Version

Before publishing v1.0.1, the latest version is v1.0.0.

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "version": "1.0.0",
  "links": [
    {
      "href": "https://www.lateral-robotics.com/portal/items/01234567-89ab-cdef-0123-456789abcdef",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://www.lateral-robotics.com/portal/items/01234567-89ab-cdef-0123-456789abcdef",
      "rel": "latest-version",
      "type": "application/json"
    },
    {
      "href": "https://your-org.com/data-products/map/version-history.md",
      "rel": "version-history",
      "type": "text/markdown"
    }
  ]
}

After publishing v1.0.1, the older version v1.0.0 points to the newer version.

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "version": "1.0.0",
  "links": [
    {
      "href": "https://www.lateral-robotics.com/portal/items/01234567-89ab-cdef-0123-456789abcdef",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://www.lateral-robotics.com/portal/items/abcdef0123-4567-89ab-cdef-0123456789abcdef",
      "rel": "successor-version",
      "type": "application/json"
    },
    {
      "href": "https://www.lateral-robotics.com/portal/items/abcdef0123-4567-89ab-cdef-0123456789abcdef",
      "rel": "latest-version",
      "type": "application/json"
    },
    {
      "href": "https://your-org.com/data-products/map/version-history.md",
      "rel": "version-history",
      "type": "text/markdown"
    }
  ]
}

The newer version points back to the previous version.

{
  "id": "abcdef0123-4567-89ab-cdef-0123456789abcdef",
  "version": "1.0.1",
  "links": [
    {
      "href": "https://www.lateral-robotics.com/portal/items/abcdef0123-4567-89ab-cdef-0123456789abcdef",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://www.lateral-robotics.com/portal/items/abcdef0123-4567-89ab-cdef-0123456789abcdef",
      "rel": "latest-version",
      "type": "application/json"
    },
    {
      "href": "https://www.lateral-robotics.com/portal/items/01234567-89ab-cdef-0123-456789abcdef",
      "rel": "predecessor-version",
      "type": "application/json"
    },
    {
      "href": "https://your-org.com/data-products/map/version-history.md",
      "rel": "version-history",
      "type": "text/markdown"
    }
  ]
}

Deprecating a Version

A release may need to be deprecated if it should no longer be used, but still needs to remain available for historical reference.

For example, a map release may be deprecated if:

it contains known geometry errors
it was created with an outdated processing pipeline
it no longer matches the active operating domain
it has been superseded by a newer validated release

To deprecate a version:

Navigate to the Portal Object that should be deprecated.
Set deprecated to true.
Make sure the deprecated Portal Object still has a self link.
Make sure the deprecated Portal Object links to the current version using latest-version.
Preserve existing predecessor-version and successor-version links unless the lineage itself is incorrect.
Add an entry to the version history explaining why the version was deprecated.

Example:

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "version": "1.0.0",
  "deprecated": true,
  "links": [
    {
      "href": "https://www.lateral-robotics.com/portal/items/01234567-89ab-cdef-0123-456789abcdef",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "https://www.lateral-robotics.com/portal/items/abcdef0123-4567-89ab-cdef-0123456789abcdef",
      "rel": "successor-version",
      "type": "application/json"
    },
    {
      "href": "https://www.lateral-robotics.com/portal/items/abcdef0123-4567-89ab-cdef-0123456789abcdef",
      "rel": "latest-version",
      "type": "application/json"
    },
    {
      "href": "https://your-org.com/data-products/map/version-history.md",
      "rel": "version-history",
      "type": "text/markdown"
    }
  ]
}

Deprecation does not remove the version from history. It only communicates that the version should no longer be used for new work.

Replacing a Version

A release may need to be replaced if it was published incorrectly and a corrected version is created later.

For example, suppose v1.0.1 contains an error and is replaced by v1.1.0.

In this case, do not remove v1.0.1 from the release history. Instead, preserve the lineage and mark v1.0.1 as deprecated.

The replacement workflow is:

Create a new Portal Object for the corrected version.
Add a self link to the corrected version.
Add a predecessor-version link from the corrected version to the replaced version.
Add a successor-version link from the replaced version to the corrected version.
Set deprecated to true on the replaced version.
Add or update latest-version links on older versions so they point to the corrected latest version.
Add an entry to the version history explaining why the replacement was created.

Example:

`v1.0.0` -> `v1.0.1` -> `v1.1.0`
           \_ (deprecated)

In this model, v1.0.1 remains part of the historical chain, but clients can clearly see that it has been deprecated and replaced by v1.1.0.

Recommended rules

Geoportal recommends the following rules for map release management.

Every Portal Object should have a self link

Each Portal Object should include a self link that points to its canonical URL.

This gives clients a stable way to identify the object they are currently viewing.

Older versions should point to the latest version

Any version should include a latest-version link that points to the current latest version.

The current latest version requires a latest-version link to itself.

Standard map releases should use linear lineage

For standard map release workflows, each version should have at most one immediate predecessor and at most one immediate successor.

This makes the release history easy for clients to navigate and easy for users to understand.

Deprecated versions should stay discoverable

Deprecated versions should not be deleted from the version lineage.

Instead, they should set deprecated to true and link to the current recommended version.

This preserves auditability and allows clients to understand the full history of a map product.

Version history should explain why releases changed

A version-history resource should explain what changed between versions.

Example Version History

A version-history resource can be stored as Markdown. Here’s an example:

# Map Version History

## 1.1.1

Corrected lane connectivity issue

- Replaces version 1.1.0
- Version 1.1.0 is deprecated

## 1.1.0

Expanded coverage area

- Added new lane topology

## 1.0.0

Initial release.

- Includes new operating domain

Client Behavior

Clients should use the versioning links to help users understand release status.

When a client opens a Portal Object, it should:

Read the object’s self link to identify the current resource.
Check whether deprecated is true.
If the object is deprecated, look for a successor-version link.
Use predecessor-version and successor-version links to show nearby versions.
Use the version-history link to show release notes or changelog information.
Use the latest-version link to show the current latest version.

This allows clients to warn users when they are viewing old or deprecated data, while still allowing them to inspect the full release history.

Summary

Map Versioning and Release Management allows Geoportal to act as a CMS for robotics map data.

Each release is represented as a Portal Object. Portal Objects are connected with versioning links that describe how releases relate to each other over time.

For standard map releases, Geoportal recommends a linear version history:

`v1.0.0` -> `v1.0.1` -> `v1.1.0`

Older versions point to the current version with latest-version. Newer versions point backward with predecessor-version. Older versions point forward with successor-version. Deprecated versions stay in the lineage, but are marked with deprecated: true.

This gives robotics teams a clear, auditable way to publish, inspect, deprecate, and replace map releases over time.