Creating Curb Objects

curbs/README.md

@@ -22,6 +22,8 @@ There are four different endpoints that are part of the Curbs API:
   - A [Curb Area](#curb-area) is a larger area of interest, such as a neighborhood or corridor, that
     could be used to show proximity, approaches, conflicts, circling, or other activity. Curb areas
     are *optional*.
+  - A [Curb Object](#curb-object) is a physical item or asset located adjacent to or within a curb space
+    that is grouped under a certain type and contains a unique set of attributes. Curb objects are *optional*.
   - A [Curb Policy](#policy) A Policy object is a rule that allows or prohibits a particular set of 
     users from using a particular curb at a particular time or times.  Curb policies are *optional* 
     but recommended with Curb Zones.
@@ -38,14 +40,19 @@ There are four different endpoints that are part of the Curbs API:
   - [Query Curb Areas](#query-curb-areas)
   - [Query Curb Spaces](#query-curb-spaces)
   - [Query Curb Policies](#query-curb-policies)
+  - [Query Curb Objects](#query-curb-objects)
   - [Fetch a Curb Zone](#fetch-a-curb-zone)
   - [Fetch a Curb Area](#fetch-a-curb-area)
   - [Fetch a Curb Space](#fetch-a-curb-space)
   - [Fetch a Curb Policy](#fetch-a-curb-policy)
+  - [Fetch a Curb Object](#fetch-a-curb-object)
 - [Data Objects](#data-objects)
   - [Curb Zone](#curb-zone)
   - [Curb Area](#curb-area)
   - [Curb Space](#curb-space)
+  - [Curb Object](#curb-object)
+    - [Object Types](#object-types)
+    - [Object Type Attributes](#object-type-attributes) 
   - [Policy](#policy)
     - [Rule](#rule)
       - [Activities](#activities)
@@ -147,6 +154,26 @@ All query parameters are optional.
 
 [Top][toc]
 
+## Query Curb Objects
+
+Endpoint: `/curbs/objects`  
+Method: `GET`  
+`data` Payload: a JSON object with a `objects` field containing an array of [Curb Object](#curb-object) objects.
+
+_Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._
+
+### Query Parameters
+
+All query parameters are optional.
+
+| Name         | Type      | Description                                    |
+| ------------ | --------- | ---------------------------------------------- |
+| `time` | [Timestamp][ts] | Only the most recently updated objects as of this time will be returned. |
+| `zone` | [UUID][uuid]    | The ID of a [Curb Zone](#curb-zone). If specified, only return Curb Objects associated within this zone. |
+| `space`| [UUID][uuid]    | The ID of a [Curb Space](#curb-space). If specified, only return Curb Objects associated within this space. |
+
+[Top][toc]
+
 ##  Fetch a Curb Zone
 
 Endpoint: `/curbs/zones/<id>`  
@@ -210,6 +237,24 @@ This endpoint takes no query parameters.
 
 [Top][toc]
 
+## Fetch a Curb Object
+
+Endpoint: `/curbs/objects/<id>`  
+Method: `GET`  
+`data` Payload: the [Curb Object](#curb-object) object with the ID provided in the path.
+
+_Optional endpoint. If not implemented, the server should reply with `501 Not Implemented`._
+
+### Query Parameters
+
+All query parameters are optional.
+
+| Name         | Type            | Description                                    |
+| ------------ | --------------- | ---------------------------------------------- |
+| `time`       | [Timestamp][ts] | Availability data (if supplied) will be returned as of this time. |
+
+[Top][toc]
+
 # Data Objects 
 
 ## Curb Zone
@@ -263,6 +308,7 @@ A Curb Zone is represented as a JSON object, whose fields are as follows:
 | `entire_roadway`| Boolean | Optional | If "true", this curb location takes up the entire width of the roadway (which may be impassible for through traffic when the Curb Zone is being used for parking or loading). This is a common condition for alleyways. If `entire_roadway` is `true`, `street_side` MUST NOT be present. |
 | `curb_area_ids`| Array of [UUID][uuid] | Optional | The ID(s) of the [Curb Areas](#curb-area) that this Curb Zone is a part of. If specified, the areas identified MUST be retrievable through the Curb API and its geographical area MUST contain that of the Curb Zone. |
 | `curb_space_ids`| Array of [UUID][uuid] | Optional | The ID(s) of the [Curb Spaces](#curb-space) that this Curb Zone contains. If specified, the spaces identified MUST be retrievable through the Curb API and its geographical area MUST be contained in this Curb Zone. |
+| `curb_object_ids` | Array of [UUID][uuid] | Optional | The ID(s) of the [Curb Objects](#curb-object) that this Curb Zone is related to, in particular what Objects are in the Zone's areas of influence. For example, a pay station being used for multiple paid parking zones, a locker for a commercial loading zone, or a camera monitoring several zones. If specified, the objects identified MUST be retrievable through the Curb API. Curb Objects can be related to a Curb Space or a Curb Zone. |
 
 [Top][toc]
 
@@ -312,11 +358,12 @@ A Curb Space is represented as a JSON object whose fields are as follows:
 | Name   | Type   | Required/Optional   | Description   |
 | ------ | ------ | ------------------- | ------------- |
 | `curb_space_id` | [UUID][uuid] | Required | The ID of the curb space. |
-| `geometry` | [Polygon][polygon] | Required |The spatial extent of this curb location. |
+| `geometry` | [Polygon][polygon] | Required | The spatial extent of this curb location. |
 | `name` | String | Optional | The name of this curb space for reference. |
 | `published_date` | [Timestamp][ts] | Required | The date/time that this curb area was first published in this data feed. |
 | `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb area were last updated. This helps consumers know that some fields may have changed. |
 | `curb_zone_id` | [UUID][uuid] | Required | The ID of the Curb Zone this space is within. The geometry of the specified Curb Zone MUST contain the geometry of this space. |
+| `curb_object_ids` | Array of [UUID][uuid] | Conditionally Required | The ID(s) of the [Curb Objects](#curb-object) that this Curb Space is related to, in particular what Objects are in the Space's areas of influence. For example, a meter being used for two paid parking spcaes, a locker for a commercial loading space, or a camera monitoring several spaces. If specified, the objects identified MUST be retrievable through the Curb API. Curb Objects can be related to a Curb Space or a Curb Zone.|
 | `space_number` | Integer | Optional | The sequence number of this space within its Zone. If specified, two spaces within the same Curb Zone MUST NOT share a space number, and space numbers SHOULD be consecutive positive integers starting at 1. |
 | `length` | Integer | Required | Length in centimeters of this Space. If comparing the length of a vehicle to that of a space, note that vehicles may have to account for a buffer for doors, mirrors, bumpers, ramps, etc. |
 | `width` | Integer | Optional | Width in centimeters of this Space. | If comparing the length of a vehicle to that of a space, note that vehicles may have to account for a buffer for doors, mirrors, bumpers, ramps, etc. |
@@ -325,6 +372,87 @@ A Curb Space is represented as a JSON object whose fields are as follows:
 
 [Top][toc]
 
+## Curb Object
+
+Defines individual assets located adjacent to, overlapping, within, or associated with a Curb Space or Curb Zone. Important notes about Curb Objects:
+
+  - Curb Objects can be located anywhere: within, beside, or overlapping with Curb Zones, Spaces, or other Curb Objects
+  - Curb Objects must be related to either a Curb Space or Curb Zone
+  - Curb Objects do not typically have Curb Policies linked directly to them (unless the object is directly aligned with a single Policy, using the optional `curb_policy_id` field). Associated Curb Policies can be found by looking at the related Curb Zone (either directly or through the Curb Space).
+  - Unlike Zones and similar to Spaces, Objects may be updated as needed, with a new `curb_object_id` being optionally assigned by the city
+
+A Curb Object is represented as a JSON object whose fields are as follows:
+
+| Name   | Type   | Required/Optional   | Description   |
+| ------ | ------ | ------------------- | ------------- |
+| `curb_object_id` | [UUID][uuid] | Required | The ID of the curb object. |
+| `geometry` | [Point][point] | Required |The spatial location of this curb object location. This can represent the approximate center of the object, or the centroid location of the object, depending on its size and shape. |
+| `curb_zone_id` | [UUID][uuid] | Conditionally Required | The ID of the Curb Zone this object is physically in or closest to. The geometry of the specified Curb Zone does not need to directly relate to the geometry of this object. Either a Zone or Space ID is required for an Object. |
+| `curb_space_id` | [UUID][uuid] | Conditionally Required | The ID of the Curb Space this object is physically in or closest to. The geometry of the specified Curb Space does not need to directly relate to the geometry of this object. Either a Zone or Space ID is required for an Object. |
+| `curb_policy_id` | [UUID][uuid] | Optional | ID of [Policy object](#policy) that is directly associcated with this curb object. For example, `signage` or `paint` that relates to a single policy. |
+| `object_type` | [Object Types](#object-types) String | Required | The categrory of the curb object. Value is one of the [Object Types](#object-types). |
+| `name` | String | Required | A short name of this curb object for reference. |
+| `description` | String | Optional | A more detailed description of the object if needed. |
+| `owner` | String | Optional | The name of the agency, department, etc responsibile for maintaining this object. |
+| `operator` | String | Optional | The name of the agency, department, etc responsibile for operating this object. |
+| `object_shape` | [Polygon][polygon] | Optional | A simplified geometric outline of this object. Recommended for objects that are an unusual shape and may affect curb activities. |
+| `object_line` | [LineString][linestring] | Optional | A simplified geometric line defining this object. Recommended for objects that may affect or help define curb activities, like `paint`. |
+| `linear_distance` | Integer | Optional | Parallel distance from the side of the object to the linear referencing start point of the curb, in centimeters. |
+| `perpendicular_distance` | Integer | Optional | Perpendicular distance from the front of the object to the curb edge start/end, in centimeters. This distance can be negative or positive, with the positive direction being from the curb towards the sidewalk. |
+| `max_length` | Integer | Optional | Maximum, bounding box length of the object parallel to the curb, in centimeters. |
+| `max_depth` | Integer | Optional | Maximum, bounding box depth of the object perpendicular to the curb, in centimeters. |
+| `max_height` | Integer | Optional | Maximum, bounding box height of the object from the sidewalk/street surface, in centimeters. |
+| `published_date` | [Timestamp][ts] | Required | The date/time that this curb object was first published in this data feed. |
+| `last_updated_date` | [Timestamp][ts] | Required | The date/time that the properties of ths curb object were last updated. This helps consumers know that some fields may have changed. |
+| `external_object_id` | String | Optional | A unique identifier for this object from an external source, like `external_object_url`. |
+| `external_object_url` | URL | Optional | A URL link to a data feed that contains the `external_object_id`. |
+
+[Top][toc]
+
+### Object Types
+
+The following object types may be specified for Curb Objects. This list is NOT meant to be exhaustive as users have the ability to add objects to this list that may be unique to their city. Descriptions have been provided with each object type where warranted. New object types may be generated to reflect local curb uses, but when possible the following well-known recommended values should be used. If multiple similar values apply, then use the more descriptive/specific value when possible. Unique object type attributes for each object type are not included in this version of the specification. As use of Curb Objects grows or specific use cases become more involved, common object type attributes can be added.
+
+**Well-known values:**
+
+Mobility Related
+- `signage` - street sign or any regulation signs related to the curb
+- `bus_stop` - either a sign, shelter, or zone
+- `bike_rack` - somewhere to lock or store a bike
+- `scooter_parking` - dedicated location to lock or store scooters
+- `ev_charging` - charging station for electric devices
+- `ramp` - a curb drop down for accessibility needs
+- `meter` - a device to pay for parking, either single or multi space
+- `pay_station` - a device to pay for parking, applicable for an entire zone
+- `paint` - curb paint, defining a policy or rule
+
+Curbside Infrastructure 
+- `lighting`
+- `signal_cabinet`
+- `utility_box` 
+- `fire_hydrant` 
+- `surveillance_camera`
+
+Curbside Obstacles
+- `barrier`
+- `bollard`
+- `street_trees`
+- `planter`
+- `drinking_fountain`
+- `toilet`
+- `bench`
+- `sculpture`
+- `art`
+- `fountain`
+- `solid_waste_bins`
+- `post_box`
+- `locker`
+
+Other
+- `food_vendor`
+
+[Top][toc]
+
 ## Policy
 
 A Policy object is a rule that allows or prohibits a particular set of users from using a particular curb at a particular time or times. Multiple Policy objects together define the full extent of regulations within a [Curb Zone](#curb-zone). The design of the Policy object borrows heavily from the work of the [CurbLR](https://github.com/curblr/curblr-spec) project, with additions for the larger scope of CDS.
@@ -528,3 +656,5 @@ See a series of [CDS Curbs endpoint examples](examples.md) to use as templates.
 [uuid]: /general-information.md#uuid
 [ts]: /general-information.md#timestamp
 [polygon]: /general-information.md#polygon
+[linestring]: /general-information.md#linestring
+[point]: /general-information.md#point

events/README.md

@@ -63,6 +63,7 @@ All query parameters are optional.
 | `curb_area_id`  | [UUID][uuid] | The ID of a [Curb Area](#curb-area). If specified, only return events occurring within this area. |
 | `curb_zone_id`  | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return events occurring within this zone. |
 | `curb_space_id` | [UUID][uuid] | The ID of a [Curb Space](#curb-space). If specified, only return events occurring within this space. |
+| `curb_object_id` | [UUID][uuid] | The ID of a [Curb Object](#curb-object). If specified, only return events occurring at this object. |
 
 [Top][toc]
 
@@ -83,6 +84,7 @@ All query parameters are optional.
 | `curb_area_id`  | [UUID][uuid] | The ID of a [Curb Area](#curb-area). If specified, only return sensor statuses within this area. |
 | `curb_zone_id`  | [UUID][uuid] | The ID of a [Curb Zone](#curb-zone). If specified, only return sensor statuses within this zone. |
 | `curb_space_id` | [UUID][uuid] | The ID of a [Curb Space](#curb-space). If specified, only return sensor statuses within this space. |
+| `curb_object_id` | [UUID][uuid] | The ID of a [Curb Object](#curb-object). If specified, only return sensor statuses at this object. |
 
 [Top][toc]
 
@@ -106,6 +108,7 @@ A Curb Event is represented as a JSON object, whose fields are as follows:
 | `curb_zone_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL _event_types_. |
 | `curb_area_ids` | Array of [UUID][uuid] | Conditionally Required | Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area, if known and used, for these event_types: _enter_area, exit_area, park_start, park_end_ |
 | `curb_space_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space, if known and used, for these event_types: _park_start, park_end, enter_area, exit_area_ |
+| `curb_object_id` | [UUID][uuid] | Conditionally Required | Unique ID of the Curb Object where the event occurred. Required for events that occurred at a known Curb Object, if known and used, for these event_types: _park_start, park_end, enter_area, exit_area_ |
 | `data_source_type` | Enum [Source Type](#source-type) | Required | General category of the source creating the event. |
 | `data_source_operator_id` | [UUID][uuid] | Conditionally Required | Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, or the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the [data_source_operators.csv](/data_source_operators.csv) file, and optional for others. Read our [How to Get a Data Source Operator ID](https://github.com/openmobilityfoundation/curb-data-specification/wiki/Adding-a-CDS-Data-Source-Operator-ID) guide. An agency at their discretion may allow a small, local company to simply provide a consistent `data_source_operator_name` string instead of this field, otherwise this field is required. |
 | `data_source_operator_name` | String | Optional | Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with `data_source_operator_id` or on its own for small operators at the discretion of the city. |

general-information.md

@@ -13,6 +13,8 @@ This document contains specifications and common concepts that are shared betwee
 - [Geographic Data](#geographic-data)
   - [Geographic Telemetry Data](geographic-telemetry-data)
   - [Polygon](#polygon)
+  - [LineString](#linestring)
+  - [Point](#Point)
   - [Intersection Operation](#intersection-operation)
 - [Pagination](#pagination)
 - [Range Boundaries](#range-boundaries)
@@ -101,7 +103,7 @@ Because of unreliability of some device clocks and other factors, sensors and op
 
 # Geographic Data
 
-References to geographic datatypes (Point, MultiPolygon, etc.) imply coordinates encoded in the [WGS 84 (EPSG:4326)][wgs84] standard GPS or GNSS projection expressed as [Decimal Degrees][decimal-degrees]. 
+References to geographic datatypes (Point, MultiPolygon, LineString, etc.) imply coordinates encoded in the [WGS 84 (EPSG:4326)][wgs84] standard GPS or GNSS projection expressed as [Decimal Degrees][decimal-degrees]. 
 
 ## Geographic Telemetry Data
 
@@ -156,6 +158,36 @@ A polygon is a GeoJSON geometry of type `"Polygon"` as defined in
 }
 ```
 
+## LineString
+
+A linestring is a GeoJSON geometry of type `"LineString"` (polyline) as defined in
+[RFC 7946 3.1.6](https://www.ietf.org/rfc/rfc7946.txt). An example linestring is:
+
+```
+{
+  "type": "LineString",
+  "coordinates": [[
+    [-73.982105, 40.767932],
+    [-73.973694, 40.764551],
+    [-73.970913, 40.763627]
+  ]]
+}
+```
+
+## Point
+
+A point is a GeoJSON geometry of type `"Point"` as defined in
+[RFC 7946 3.1.6](https://www.ietf.org/rfc/rfc7946.txt). An example point is:
+
+```
+{
+  "type": "Point",
+  "coordinates": [
+    -73.982105, 40.767932
+   ]
+}
+```
+
 ## Intersection Operation
 
 For the purposes of this specification, the intersection of two geographic datatypes is defined according to the [`ST_Intersects` PostGIS operation][st-intersects]