[FEATURE] Extensible tag classification model discovery through Entry Points by RoelBollens-TomTom · Pull Request #463 · OvertureMaps/schema

Roel Bollens (RoelBollens-TomTom) · 2026-03-10T23:48:57Z

Extensible tag classification model discovery through Entry Points

This replaces the hardcoded model classification system with tag-based classification model discovery through Entry Points. This is based on #440 by Seth and several schema (ad-hoc) coding sessions where Seth, Vic, Dana, Tristan and Roel participated in.

Model discovery moved into system, eliminating assumptions about Overture in the process. The hardcoded namespace concept ("overture", "annex") and the ModelKind classifier is replaced with tags -- string labels derived by tag providers. Tags become the filtering, grouping, and classification mechanism for model discovery, driven by introspection and package metadata rather than central coordination.

system provides generic tag-based grouping without understanding what any particular tag means. Any package can register tag providers that classify models without special support in the discovery layer.

Purpose

Tags serve three roles:

CLI filtering: select subsets of models for output and codegen (--tag system:feature, --tag draft)
Classification and endorsement: distinguish features from extensions, mark models as vetted or approved by an authority
Marketplace taxonomy: browse and classify models and extensions in a future extension catalog

These roles overlap -- a tag like overture:theme=buildings serves both filtering and taxonomy. The design accommodates this overlap through structured tags that encode both ownership and dimension.

Tag Format

Tags are strings following the pattern [prefix:]key[=value]:

Plain: overture, draft, feature
Prefixed: system:extension -- : separates ownership
Prefixed k/v: overture:theme=buildings

: signals ownership and enables prefix reservation (see Privileged Packages and Tag Reservation). = signals a dimension with a value (groupable via --group-by). One level of each -- no nested colons or multiple = signs.

Minimal launch set

Tag	Meaning
`feature` (was: `system:feature`)	This model is a feature type (has geometry, inherits from Feature
`overture:theme=<theme>`	Which Overture theme this belongs to (e.g., `buildings`, `transportation`)
`overture` (was: `overture:official`)	Placeholder for a lifecycle/endorsement tag — exact name deferred pending Dana and Tristan's work on extension lifecycle

Reserved tags

Tags can be reserved either as simple tags or by namespaces. These are the tags and namespaces that are currently reserved:

Tag	Reserved for use by
`feature`	Tag providers from `overture-schema-system`
`overture`	Tag providers from `overture-schema-core`
`overture:*`	Tag providers from `overture-schema-core`
`system:*`	Tag providers from `overture-schema-system`

Extensions

Additional extensions and accompanied tags will be introduced in a future PR. Extensions allows to augment existing types with new fields (columns).

Tag	Meaning
system:extension	This model is an extension (adds columns/fields to an existing type)

CLI

The list-types command has been updated to support filtering and grouping by tags. Currently, it no longer displays the description or fully qualified class name. The json-schema and validate commands from the overture-schema cli and generate command from the overture-codegen cli have been updated to be able to filter on tags instead of filtering by theme and type. Further changes can be introduced in a future update.

Examples

% overture-schema list-types
address            feature  overture  overture:theme=addresses
bathymetry         feature  overture  overture:theme=base
building           feature  overture  overture:theme=buildings
building_part      feature  overture  overture:theme=buildings
connector          feature  overture  overture:theme=transportation
division           feature  overture  overture:theme=divisions
division_area      feature  overture  overture:theme=divisions
division_boundary  feature  overture  overture:theme=divisions
infrastructure     feature  overture  overture:theme=base
land               feature  overture  overture:theme=base
land_cover         feature  overture  overture:theme=base
land_use           feature  overture  overture:theme=base
place              feature  overture  overture:theme=places
segment            feature  overture  overture:theme=transportation
sources            overture
water              feature  overture  overture:theme=base

% overture-schema list-types --group-by overture:theme
overture:theme=addresses (1)
→ address            feature  overture  overture:theme=addresses

overture:theme=base (6)
→ bathymetry         feature  overture  overture:theme=base
→ infrastructure     feature  overture  overture:theme=base
→ land               feature  overture  overture:theme=base
→ land_cover         feature  overture  overture:theme=base
→ land_use           feature  overture  overture:theme=base
→ water              feature  overture  overture:theme=base

overture:theme=buildings (2)
→ building           feature  overture  overture:theme=buildings
→ building_part      feature  overture  overture:theme=buildings

overture:theme=divisions (3)
→ division           feature  overture  overture:theme=divisions
→ division_area      feature  overture  overture:theme=divisions
→ division_boundary  feature  overture  overture:theme=divisions

overture:theme=places (1)
→ place              feature  overture  overture:theme=places

overture:theme=transportation (2)
→ connector          feature  overture  overture:theme=transportation
→ segment            feature  overture  overture:theme=transportation

% overture-schema list-types --tag overture --exclude-tag overture:theme=base 
address            feature  overture  overture:theme=addresses
building           feature  overture  overture:theme=buildings
building_part      feature  overture  overture:theme=buildings
connector          feature  overture  overture:theme=transportation
division           feature  overture  overture:theme=divisions
division_area      feature  overture  overture:theme=divisions
division_boundary  feature  overture  overture:theme=divisions
place              feature  overture  overture:theme=places
segment            feature  overture  overture:theme=transportation
sources            overture

Deviations

Tag providers are additive only and can't remove existing tags.
The execution order of tag providers is non-deterministic.
There is currently no warning on a tag amount limit
Agreed minimal tag set deviates from coding session outcome to make them less clunky by dropping namespace

Seth Fitzsimmons (mojodna) · 2026-03-12T05:08:23Z

+        filters = []
+
+        if tags:
+            filters.append(lambda key: all(tag in key.tags for tag in tags))


all() here means --tag foo --tag bar requires BOTH tags (AND). Is that the intended semantics, or should repeated --tag flags use OR?

This was intentional, but I guess this should still be formalized so I'll leave this open for discussion.

from the coding session minutes:

--tag semantics are AND
The mockups assume --tag overture --tag system:feature means "must have both tags" (AND). This contradicts the design doc's stated OR semantics. The group implicitly operated with AND throughout the exercise and no one objected. This should be formalized.

Ah, great. I'm good with that; it didn't track with how I'd been thinking about it earlier is all.

I'll still leave this open. Maybe after refactoring the other CLI commands opinions might change.

What we discussed this morning in the coding session: AND makes the most sense for CLI list, but there are other use cases where OR fits better.

I did some very cursory LLM-driven research about common CLI paradigms that support both AND and OR in filtering. The best example I could come up with were kubectl label selectors with -l and docker filters, but none of them fit our exact use case.

I thought about it a bit and came up with some priorities:

CLI should support both AND and OR.

Should not use any special shell characters, especially characters like ! that can get expanded even within double quotes.

The most common use cases should be simple.

Should not require a lot of typing.

The best idea I can come up with is to allow --tag to express an "OR of ANDs" by supporting multiple --tags values.

--tag can be repeated as many times as you want.

Each --tag supports as plus-sign-separated list. (Alternative: comma.)

Within a --tag the plus-separated values form an AND expression.

The multiple --tag arguments are unioned together as a big OR expression.

This allows you to express an "OR of ANDs" which is probably powerful enough for most CLI use cases.

I would also suggest allowing * wildcards to further strengthen the CLI power.

Examples

Get all models matching single tag, foo.

--tag foo

Get all models that are both foo AND bar.

--tag foo+bar

Get all models that are in an Overture theme AND also bar.

--tag overture:theme=*+bar

Get all models that are either foo OR bar.

--tag foo --tags bar

Get all models that are either Overture transportation features or Overture places features.

--tag feature+overture:theme=transportation --tag feature+overture:theme=places

--tag foo+bar I'm less a fan of, because it introduces a query language in the value. I'd rather keep --tag as a simple repeatable flag. But I like adding the wildcard for namespace:* and ns:predicate=*.

A git log style --all-match is something I considered to switch --tag values from OR logic to AND. My concern with that is that some commands may want AND by default, and that still doesn't give a clean way to support both AND and OR on the same command, if that's at all desired.

Alternative ideas:

--tag to include, --filter to exclude

-i/--include to include, -e/--exclude to exclude

existing is --tags and --exclude-tags

Seth Fitzsimmons (mojodna) · 2026-03-12T05:10:10Z

+}
+TAG = r"[a-z0-9][a-z0-9_-]*"
+NAMESPACE_TAG = r"[a-z0-9]+:[a-z0-9]+(?:=[a-z0-9_.-]+)?"
+TAG_RE = re.compile(rf"^(?:{TAG}|{NAMESPACE_TAG})$")


TAG allows hyphens and underscores ([a-z0-9_-]), but NAMESPACE_TAG's key segment doesn't — acme:my-ext would fail validation even though my-ext is a valid plain tag. Intentional?

The tag definition/validation needs some more love. I added a regex to have some validation but very little thought went into it. Same where TAG doesn't allow for decimal points/periods were a value in a namespace tag would (3.14 would fail but acme:pi=3.14 will pass).

That handling of numbers makes sense to me. Raw tags with decimals feels somewhat confusing, so while it's restrictive, I could justify it.

Well a standalone number might be odd, but i support it could also be something else like overturemaps.org as a tag, which it currently doesn't allow.

TAG allows hyphens and underscores ([a-z0-9_-]), but NAMESPACE_TAG's key segment doesn't — acme:my-ext would fail validation even though my-ext is a valid plain tag. Intentional?

To Seth Fitzsimmons (@mojodna)'s point I would suggest the same pattern should be used for both.

Discussed in the coding sesh and ...

Namespace and predicate have the same pattern.

Which is: all lowercase, start alphanumeric, then can be alphanumeric or - or _ or ..

Value can include uppercase and need not start alphanumeric.

Tag matching/combining/filtering/jiggering is case sensitive.

Victor Schappert (vcschapp)

Let some comments, but I'm generally aligned and would merge once Roel Bollens (@RoelBollens-TomTom) and Seth Fitzsimmons (@mojodna) are jointly aligned on merging.

Left some thoughts on the AND/OR issue in the CLI, probably above there somewhere. 👆

Victor Schappert (vcschapp) · 2026-03-25T17:13:24Z

+logger = logging.getLogger(__name__)
+
+
+RESERVED_TAGS: dict[str, set[str]] = {


Are these various CONSTANTS meant to be part of the public interface or are they internal use only?

If internal use only, can we give them the appropriate underscore prefix?

Victor Schappert (vcschapp) · 2026-03-25T17:13:38Z

+
+from overture.schema.system.feature import Feature
+
+logger = logging.getLogger(__name__)


This seems private, should i get the appropriate underscore prefix?

Victor Schappert (vcschapp) · 2026-03-25T17:18:21Z

+RESERVED_TAGS: dict[str, set[str]] = {
+    "overture": {"overture-schema-core"},
+    "feature": {"overture-schema-system"},
+}


I thought feature_provider was intentionally emitting feature rather than system:feature to be less clunky, per the PR description.

I understood from the PR description that you can reserve both plain tags and namespaces.

Personally I like this approach.

Victor Schappert (vcschapp) · 2026-03-25T17:20:33Z

+}
+TAG = r"[a-z0-9][a-z0-9_-]*"
+NAMESPACE_TAG = r"[a-z0-9]+:[a-z0-9]+(?:=[a-z0-9_.-]+)?"
+TAG_RE = re.compile(rf"^(?:{TAG}|{NAMESPACE_TAG})$")


TAG allows hyphens and underscores ([a-z0-9_-]), but NAMESPACE_TAG's key segment doesn't — acme:my-ext would fail validation even though my-ext is a valid plain tag. Intentional?

To Seth Fitzsimmons (@mojodna)'s point I would suggest the same pattern should be used for both.

Victor Schappert (vcschapp) · 2026-03-25T17:22:09Z

+ModelKeyFilter: TypeAlias = Callable[[ModelKey], bool]
+
+
+def generate_tags(


_private?

Victor Schappert (vcschapp) · 2026-03-25T17:23:54Z

+TagProvider: TypeAlias = Callable[[type[BaseModel], ModelKey, set[str]], set[str]]
+
+ModelDict: TypeAlias = dict[ModelKey, type[BaseModel]]
+
+TagProviderDict: TypeAlias = dict[TagProviderKey, TagProvider]
+
+ModelKeyFilter: TypeAlias = Callable[[ModelKey], bool]


Are any of these intended to be _Private, e.g. maybe TagProviderDict?

Victor Schappert (vcschapp) · 2026-03-25T17:33:42Z

+                    key = replace(
+                        key,
+                        tags=frozenset(generate_tags(model_class, key, tag_providers)),
+                    )


Basically switching the return type to tuple[str] from set[str]?

I have no opinion on this.

You could go the other way and return collections.abc.Iterable[str] - that way anything that can produce a sequence of strings via iteration would suffice.