Skip to content

Commit f8385af

Browse files
jwassjwass
authored
Taxonomy property for new places category system (#420)
* Initial commit of new places taxonomy * Fix TX region * Add operating_status to bad-categories-value * Fix mistakenly change alternate -> alternates * Revert change to bad categories counterexample * Add pydantic model for new taxonomy * Fix up place baseline schema json * Copy examples/couterexamples to references. Update docs * Update main place.yaml file to reflect unique/minItems constraints * Add backtick and reference to Places doc page * Update baseline json
1 parent 1724b46 commit f8385af

File tree

9 files changed

+353
-5
lines changed

9 files changed

+353
-5
lines changed

‎counterexamples/places/bad-taxonomy-missing-hierarchy.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
id: overture:places:place:1
3+
type: Feature
4+
geometry:
5+
type: Point
6+
coordinates: [0, 0]
7+
properties:
8+
ext_expected_errors: ["missing property 'hierarchy'"]
9+
theme: places
10+
type: place
11+
version: 1
12+
names:
13+
primary: Place with taxonomy missing hierarchy
14+
taxonomy:
15+
primary: gas_station_sushi
16+
alternates:
17+
- gas_station
18+
- sushi_restaurant
19+
operating_status: open

‎counterexamples/places/bad-taxonomy-missing-primary.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
id: overture:places:place:1
3+
type: Feature
4+
geometry:
5+
type: Point
6+
coordinates: [0, 0]
7+
properties:
8+
ext_expected_errors: ["missing property 'primary'"]
9+
theme: places
10+
type: place
11+
version: 1
12+
names:
13+
primary: Place with taxonomy missing primary
14+
taxonomy:
15+
hierarchy:
16+
- food_and_drink
17+
- restaurant
18+
- casual_eatery
19+
- gas_station_sushi
20+
alternates:
21+
- gas_station
22+
- sushi_restaurant
23+
operating_status: open

‎examples/places/place-with-taxonomy.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
id: overture:places:place:77
3+
type: Feature
4+
geometry:
5+
type: Point
6+
coordinates: [-97.7431, 30.2672]
7+
properties:
8+
basic_category: casual_eatery
9+
taxonomy:
10+
primary: gas_station_sushi
11+
hierarchy:
12+
- food_and_drink
13+
- restaurant
14+
- casual_eatery
15+
- gas_station_sushi
16+
alternates:
17+
- gas_station
18+
- sushi_restaurant
19+
categories:
20+
primary: gas_station_sushi
21+
alternate:
22+
- gas_station
23+
- sushi_restaurant
24+
confidence: 0.85
25+
websites:
26+
- https://www.buckysgas.example.com
27+
emails:
28+
- sushi@buckysgas.example.com
29+
socials:
30+
- https://www.instagram.com/buckyssushi
31+
phones:
32+
- +1 512-555-0123
33+
brand:
34+
names:
35+
primary: Bucky's Gas & Sushi
36+
wikidata: Q9999999
37+
addresses:
38+
- freeform: "4200 South Congress Ave"
39+
locality: "Austin"
40+
region: "US-TX"
41+
postcode: "78745"
42+
country: "US"
43+
# Overture properties
44+
theme: places
45+
type: place
46+
version: 1
47+
names:
48+
primary: Bucky's Gas & Sushi
49+
common:
50+
en: Bucky's Gas and Sushi
51+
es: Gasolinera y Sushi de Bucky
52+
rules:
53+
- variant: short
54+
value: Bucky's
55+
operating_status: open

‎packages/overture-schema-places-theme/src/overture/schema/places/place.py‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,72 @@ class Categories(BaseModel):
8282
] = None
8383

8484

85+
@no_extra_fields
86+
class Taxonomy(BaseModel):
87+
"""
88+
A structured representation of the place's category within the Overture taxonomy.
89+
90+
Provides the primary classification, full hierarchy path, and alternate categories.
91+
"""
92+
93+
# Required
94+
95+
primary: Annotated[
96+
SnakeCaseString,
97+
Field(
98+
description=textwrap.dedent("""
99+
The primary, or most specific, category known about this place.
100+
101+
The `primary` category value must always equal the last or rightmost entry in the `hierarchy` field.
102+
""")
103+
),
104+
]
105+
106+
hierarchy: Annotated[
107+
list[SnakeCaseString],
108+
Field(
109+
min_length=1,
110+
description=textwrap.dedent("""
111+
The full primary hierarchy of categories known for this place, ordered from most general to most specific.
112+
An example hierarchy might be: `["food_and_drink", "restaurant", "casual_eatery", "gas_station_sushi"]`.
113+
114+
The rightmost, or most specific, value in the `hierarchy` must always be equal to the `primary` field.
115+
The basic level category of the place will typically be found in the middle of the primary hierarchy.
116+
The primary hierarchy does not include any of the alternate categories found in the `alternates` field.
117+
""").strip(),
118+
),
119+
UniqueItemsConstraint(),
120+
]
121+
122+
# Optional
123+
124+
alternates: Annotated[
125+
list[SnakeCaseString] | None,
126+
Field(
127+
min_length=1,
128+
description=textwrap.dedent("""
129+
Unordered list of additional categories that are known for this
130+
place but that are not part of the primary category hierarchy.
131+
132+
Alternate categories allow a more complete picture of the place
133+
to be surfaced when it fits multiple unconnected branches in the
134+
taxonomy. For example a gas station that also sells groceries
135+
might have primary category of "gas_station" with an alternate
136+
of "grocery_store".
137+
138+
Alternate categories are not part of the primary hierarchy or
139+
another alternate category's hierarchy.
140+
In other words, if a category is a parent in the hierarchy of another category,
141+
that category can't be a primary or alternate category itself.
142+
143+
Note as well that this field is an unordered list of extra
144+
categories and does not represent a hierarchy.
145+
""").strip(),
146+
),
147+
UniqueItemsConstraint(),
148+
] = None
149+
150+
85151
@no_extra_fields
86152
class Brand(Named):
87153
"""
@@ -175,6 +241,20 @@ class Place(OvertureFeature[Literal["places"], Literal["place"]], Named):
175241
name at the level of generality that is preferred by humans in learning and memory
176242
tasks. This category to be roughly in the middle of the general-to-specific category
177243
hierarchy.
244+
245+
The full list of basic level categories is available at https://docs.overturemaps.org/guides/places/
246+
"""
247+
).strip()
248+
),
249+
] = None
250+
taxonomy: Annotated[
251+
Taxonomy | None,
252+
Field(
253+
description=textwrap.dedent(
254+
"""
255+
A structured representation of the place's category within the Overture taxonomy.
256+
257+
Provides the primary classification, full hierarchy path, and alternate categories.
178258
"""
179259
).strip()
180260
),

‎packages/overture-schema-places-theme/tests/place_baseline_schema.json‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,48 @@
300300
],
301301
"title": "SourceItem",
302302
"type": "object"
303+
},
304+
"Taxonomy": {
305+
"additionalProperties": false,
306+
"description": "A structured representation of the place's category within the Overture taxonomy.\n\nProvides the primary classification, full hierarchy path, and alternate categories.",
307+
"properties": {
308+
"alternates": {
309+
"description": "Unordered list of additional categories that are known for this\nplace but that are not part of the primary category hierarchy.\n\nAlternate categories allow a more complete picture of the place\nto be surfaced when it fits multiple unconnected branches in the\ntaxonomy. For example a gas station that also sells groceries\nmight have primary category of \"gas_station\" with an alternate\nof \"grocery_store\".\n\nAlternate categories are not part of the primary hierarchy or\nanother alternate category's hierarchy.\nIn other words, if a category is a parent in the hierarchy of another category,\nthat category can't be a primary or alternate category itself.\n\nNote as well that this field is an unordered list of extra\ncategories and does not represent a hierarchy.",
310+
"items": {
311+
"description": "Category in snake_case format",
312+
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
313+
"type": "string"
314+
},
315+
"minItems": 1,
316+
"title": "Alternates",
317+
"type": "array",
318+
"uniqueItems": true
319+
},
320+
"hierarchy": {
321+
"description": "The full primary hierarchy of categories known for this place, ordered from most general to most specific.\nAn example hierarchy might be: `[\"food_and_drink\", \"restaurant\", \"casual_eatery\", \"gas_station_sushi\"]`.\n\nThe rightmost, or most specific, value in the `hierarchy` must always be equal to the `primary` field.\nThe basic level category of the place will typically be found in the middle of the primary hierarchy.\nThe primary hierarchy does not include any of the alternate categories found in the `alternates` field.",
322+
"items": {
323+
"description": "Category in snake_case format",
324+
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
325+
"type": "string"
326+
},
327+
"minItems": 1,
328+
"title": "Hierarchy",
329+
"type": "array",
330+
"uniqueItems": true
331+
},
332+
"primary": {
333+
"description": "\nThe primary, or most specific, category known about this place.\n\nThe `primary` category value must always equal the last or rightmost entry in the `hierarchy` field.\n",
334+
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
335+
"title": "Primary",
336+
"type": "string"
337+
}
338+
},
339+
"required": [
340+
"primary",
341+
"hierarchy"
342+
],
343+
"title": "Taxonomy",
344+
"type": "object"
303345
}
304346
},
305347
"additionalProperties": false,
@@ -377,7 +419,7 @@
377419
"type": "array"
378420
},
379421
"basic_category": {
380-
"description": "The basic level category of a place.\n\nThis field classifies places into categories at a level that most people find\nintuitive. The full list of possible values it may hold can be found at (TODO).\n\nThe basic level category, or simply basic category, is based on a cognitive science\nmodel use in taxonomy and ontology development. The idea is to provide the category\nname at the level of generality that is preferred by humans in learning and memory\ntasks. This category to be roughly in the middle of the general-to-specific category\nhierarchy.",
422+
"description": "The basic level category of a place.\n\nThis field classifies places into categories at a level that most people find\nintuitive. The full list of possible values it may hold can be found at (TODO).\n\nThe basic level category, or simply basic category, is based on a cognitive science\nmodel use in taxonomy and ontology development. The idea is to provide the category\nname at the level of generality that is preferred by humans in learning and memory\ntasks. This category to be roughly in the middle of the general-to-specific category\nhierarchy.\n\nThe full list of basic level categories is available at https://docs.overturemaps.org/guides/places/",
381423
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*$",
382424
"title": "Basic Category",
383425
"type": "string"
@@ -449,6 +491,9 @@
449491
"type": "array",
450492
"uniqueItems": true
451493
},
494+
"taxonomy": {
495+
"$ref": "#/$defs/Taxonomy"
496+
},
452497
"theme": {
453498
"const": "places",
454499
"title": "Theme",

‎reference/counterexamples/places/bad-taxonomy-missing-hierarchy.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
id: overture:places:place:1
3+
type: Feature
4+
geometry:
5+
type: Point
6+
coordinates: [0, 0]
7+
properties:
8+
ext_expected_errors: ["missing property 'hierarchy'"]
9+
theme: places
10+
type: place
11+
version: 1
12+
names:
13+
primary: Place with taxonomy missing hierarchy
14+
taxonomy:
15+
primary: gas_station_sushi
16+
alternates:
17+
- gas_station
18+
- sushi_restaurant
19+
operating_status: open

‎reference/counterexamples/places/bad-taxonomy-missing-primary.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
id: overture:places:place:1
3+
type: Feature
4+
geometry:
5+
type: Point
6+
coordinates: [0, 0]
7+
properties:
8+
ext_expected_errors: ["missing property 'primary'"]
9+
theme: places
10+
type: place
11+
version: 1
12+
names:
13+
primary: Place with taxonomy missing primary
14+
taxonomy:
15+
hierarchy:
16+
- food_and_drink
17+
- restaurant
18+
- casual_eatery
19+
- gas_station_sushi
20+
alternates:
21+
- gas_station
22+
- sushi_restaurant
23+
operating_status: open

‎reference/examples/places/place-with-taxonomy.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
id: overture:places:place:77
3+
type: Feature
4+
geometry:
5+
type: Point
6+
coordinates: [-97.7431, 30.2672]
7+
properties:
8+
basic_category: casual_eatery
9+
taxonomy:
10+
primary: gas_station_sushi
11+
hierarchy:
12+
- food_and_drink
13+
- restaurant
14+
- casual_eatery
15+
- gas_station_sushi
16+
alternates:
17+
- gas_station
18+
- sushi_restaurant
19+
categories:
20+
primary: gas_station_sushi
21+
alternate:
22+
- gas_station
23+
- sushi_restaurant
24+
confidence: 0.85
25+
websites:
26+
- https://www.buckysgas.example.com/
27+
emails:
28+
- sushi@buckysgas.example.com
29+
socials:
30+
- https://www.instagram.com/buckyssushi
31+
phones:
32+
- +1 512-555-0123
33+
brand:
34+
names:
35+
primary: Bucky's Gas & Sushi
36+
wikidata: Q9999999
37+
addresses:
38+
- freeform: "4200 South Congress Ave"
39+
locality: "Austin"
40+
region: "US-TX"
41+
postcode: "78745"
42+
country: "US"
43+
# Overture properties
44+
theme: places
45+
type: place
46+
version: 1
47+
names:
48+
primary: Bucky's Gas & Sushi
49+
common:
50+
en: Bucky's Gas and Sushi
51+
es: Gasolinera y Sushi de Bucky
52+
rules:
53+
- variant: short
54+
value: Bucky's
55+
operating_status: open

0 commit comments

Comments
 (0)