0
# Entities and Semantic Data
1

2
Semantic entity models for representing structured data like mentions, places, geographic coordinates, and generic schema.org entities within Bot Framework activities.
3

4
## Core Entity Types
5

6
### Entity Base Class
7

8
The base class for all semantic entities attached to activities.
9

10
```python { .api }
11
class Entity(Model):
12
    def __init__(self, *, type: str = None, **kwargs):
13
        """
14
        Metadata object pertaining to an activity.
15
        
16
        Parameters:
17
        - type: Type of this entity (RFC 3987 IRI)
18
        """
19
```
20

21
```python
22
from botbuilder.schema import Entity
23

24
# Create a generic entity
25
entity = Entity(type="https://schema.org/Person")
26
```
27

28
### Geographic Coordinates
29

30
Schema.org GeoCoordinates entity for representing geographic locations.
31

32
```python { .api }
33
class GeoCoordinates(Model):
34
    def __init__(self, *, elevation: float = None, latitude: float = None,
35
                 longitude: float = None, type: str = None, name: str = None, **kwargs):
36
        """
37
        GeoCoordinates (entity type: "https://schema.org/GeoCoordinates").
38
        
39
        Parameters:
40
        - elevation: Elevation of the location [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System)
41
        - latitude: Latitude of the location [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System)
42
        - longitude: Longitude of the location [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System)
43
        - type: The type of the thing
44
        - name: The name of the thing
45
        """
46
```
47

48
```python
49
from botbuilder.schema import GeoCoordinates
50

51
# Create geographic coordinates for a location
52
coords = GeoCoordinates(
53
    latitude=47.6062,
54
    longitude=-122.3321,
55
    elevation=56.0,
56
    type="https://schema.org/GeoCoordinates",
57
    name="Seattle, WA"
58
)
59
```
60

61
### Place Entity  
62

63
Schema.org Place entity for representing physical locations with addresses and coordinates.
64

65
```python { .api }
66
class Place(Model):
67
    def __init__(self, *, address=None, geo=None, has_map=None,
68
                 type: str = None, name: str = None, **kwargs):
69
        """
70
        Place (entity type: "https://schema.org/Place").
71
        
72
        Parameters:
73
        - address: Address of the place (may be `string` or complex object of
74
          type `PostalAddress`)
75
        - geo: Geo coordinates of the place (may be complex object of type
76
          `GeoCoordinates` or `GeoShape`)
77
        - has_map: Map to the place (may be `string` (URL) or complex object
78
          of type `Map`)
79
        - type: The type of the thing
80
        - name: The name of the thing
81
        """
82
```
83

84
```python
85
from botbuilder.schema import Place, GeoCoordinates
86

87
# Create a place with address and coordinates
88
place = Place(
89
    name="Microsoft Campus",
90
    address="One Microsoft Way, Redmond, WA 98052",
91
    geo=GeoCoordinates(
92
        latitude=47.6394,
93
        longitude=-122.1282,
94
        type="https://schema.org/GeoCoordinates"
95
    ),
96
    type="https://schema.org/Place"
97
)
98
```
99

100
### Thing Entity
101

102
The most generic Schema.org entity representing any "thing" that can be named and typed.
103

104
```python { .api }
105
class Thing(Model):
106
    def __init__(self, *, type: str = None, name: str = None, **kwargs):
107
        """
108
        Thing (entity type: "https://schema.org/Thing").
109
        
110
        Parameters:
111
        - type: The type of the thing
112
        - name: The name of the thing
113
        """
114
```
115

116
```python
117
from botbuilder.schema import Thing
118

119
# Create a generic thing entity
120
thing = Thing(
121
    type="https://schema.org/Organization",
122
    name="Microsoft Corporation"
123
)
124
```
125

126
## Usage Examples
127

128
### Adding Entities to Activities
129

130
```python
131
from botbuilder.schema import (
132
    Activity, ActivityTypes, Entity, Place, GeoCoordinates
133
)
134

135
# Create an activity with location entities
136
activity = Activity(
137
    type=ActivityTypes.message,
138
    text="I'm currently at the Microsoft campus.",
139
    entities=[
140
        Place(
141
            name="Microsoft Campus",
142
            address="One Microsoft Way, Redmond, WA 98052",
143
            geo=GeoCoordinates(
144
                latitude=47.6394,
145
                longitude=-122.1282
146
            ),
147
            type="https://schema.org/Place"
148
        )
149
    ]
150
)
151
```
152

153
### Working with Geographic Data
154

155
```python
156
from botbuilder.schema import GeoCoordinates, Place
157

158
def create_location_entity(name: str, lat: float, lng: float, address: str = None):
159
    """Create a location entity with coordinates."""
160
    coords = GeoCoordinates(
161
        latitude=lat,
162
        longitude=lng,
163
        type="https://schema.org/GeoCoordinates"
164
    )
165
    
166
    return Place(
167
        name=name,
168
        address=address,
169
        geo=coords,
170
        type="https://schema.org/Place"
171
    )
172

173
# Usage
174
seattle = create_location_entity(
175
    "Seattle",
176
    47.6062,
177
    -122.3321,
178
    "Seattle, WA, USA"
179
)
180
```
181

182
### Custom Entity Types
183

184
```python
185
from botbuilder.schema import Entity
186

187
# Create custom schema.org entities
188
person_entity = Entity(type="https://schema.org/Person")
189
product_entity = Entity(type="https://schema.org/Product") 
190
event_entity = Entity(type="https://schema.org/Event")
191

192
# Entities can be added to activities for semantic enrichment
193
activity.entities = [person_entity, product_entity, event_entity]
194
```
195

196
## Schema.org Integration
197

198
All entity classes follow [Schema.org](https://schema.org/) standards for structured data representation, enabling rich semantic understanding of bot conversations. The `type` field uses Schema.org IRIs to define the semantic meaning of entities.
199

200
Common Schema.org entity types used in bot scenarios:
201
- `https://schema.org/Person` - People and individuals
202
- `https://schema.org/Organization` - Companies and organizations  
203
- `https://schema.org/Place` - Physical locations
204
- `https://schema.org/Event` - Events and activities
205
- `https://schema.org/Product` - Products and services
206
- `https://schema.org/GeoCoordinates` - Geographic coordinates