Curb Architectural Decisions
As the Curb Working Group creates and refines the first draft of the Curb Data Specification (CDS), many architectural decisions are made along the way by the Working Group Steering Committee based on community discussions.
This is a point-in-time document to explain some of the key decision points and why they were made.
Many decisions have been made by bringing up to our public Working Group, and then discussing and tracking in detail in the official Discussions area. Please review these discussions for even more decisions than what are documented here.
Some cities keep their data in sync with citywide linear referencing systems; however, others may want to use CDS for ad-hoc pilots without overhauling their city's data systems. While CDS does allow and encourage linear referencing, it should be possible to use CDS without a linear referencing system if necessary.
Data formats used in CDS should be text-based and the information within them should be intelligible to human readers with moderate levels of technical and domain knowledge.
While CDS is a different spec than MDS, it should be possible and convenient to use the two in tandem when their use cases intersect.
Even though the initial use cases under consideration are related to smaller-scale pilots, the API should be designed in such a way that it can scale to cover all of the curb data in a city. This means that, for instance, it should be possible to define any curb policy within the API, not just those related to loading, and that it should be possible to query large data sets in a relatively efficient way. While not all kinds of curb policies and geometries may be equally elegant to define, all of them should be expressible.
One widely-used curb data format is CurbLR. While we have decided not to strive for compatibility with CurbLR because of the larger scope of CDS, we want it to be possible to translate existing CurbLR data for use in the Curb API easily and mechanically.
These are the reasons someone might call CDS APIs that we are keeping foremost in our minds during the design process.
- Determine the regulation of the curb immediately adjacent to a vehicle (e.g., to determine if the vehicle is parked legally)
- Find a nearby curb that can be used for a particular purpose, in order to direct a vehicle there in real time
- Analyze the policies of curbs within an area (e.g., how many loading zone spaces are there in this neighborhood?)
- Monitor the performance of a loading zone using sensor- or fleet-provided data
These are some of the more-debated technical decisions that we made in the API design process
CDS, like MDS, maintains a list of globally unique companies in the providers.csv file in this repository. This allows providers to be referenced consistently in neighboring jurisdictions, and consistency for curb users and third party software companies implementing CDS. See the discussion here.
There is an option in Events to specify a provider_name for smaller companies operating in a single city.
In Curbs API, Policies can be attached to Curbs independently, but may not be changed without creating a new policy. This is to ensure CDS consumers and curb users have clarity on what policies apply to a specific curb zone and fetch the latest information. On a related note, curb zone properties may change, including what policies apply to them, but their last_updated date will be modified and new policy ID(s) attached. See the discussion here.
Separating policy details from zone definitions allows for cross-referencing objects, a more modular design, alignment with MDS, accessing only the data you need, easier bulk changes, and smaller response sizes. See the discussion here.
While many vehicle identifiers were discussed for inclusion, for the CDS 1.0 we agreed to only include license plate number (LPN), nationally registered external number (like from USDOT), and unique vehicle UUID provided by operators. VIN and a digital permit number are not included until we have more ubiquitous real-world usage. Use of LPN will usage include guidance from our Privacy Committee. See the discussion here.
JSON is the format of all endpoints, for maximum flexibility and alignment with MDS. While GeoJSON is a standard JSON-based schema for expressing geographical data, CDS objects will not be GeoJSON Features or FeatureCollections. Rather, endpoints with geographic elements will contain GeoJSON geometries that can be manually or programmatically extracted. A converter may be made to transform objects within CDS into GeoJSON features, allowing easy geographic visualizations. We will look to usage of CDS in the real world to see if there is a demand for a native GeoJSON option. See the discussion here.
Dynamic endpoints will be required for this release (that is, it will not be possible to produce a CDS-compliant API simply by serving static files at particular URLs), but more advanced and complex querying will be left out to make it easier to implement. The need for more dynamic querying, or completely static files, will be evaluated during pilots for the next release. See the discussion here.
Each zone, policy, area, and space are given their own unique UUID, just like in MDS. This allows items to be easily cross referenced and UUIDs are unique, easy to generate, and widely supported.
UUIDs should be conserved across API invocations but new UUIDs should be generated when the properties of an object change; in particular, the geography and policies of a Curb Zone object with a given UUID are immutable (though they may be adjusted to correct errors or increase accuracy). Splitting a zone in two or changing its policies must result in new UUIDs being assigned.
This also implies that a Curb Zone has the same lifetime as the set of policies it implements. While the particular curb policies applied on a street network change more often than the locations of curbs, our choice to not require linear referencing (see above) means that we don't have a good way to talk about "the same section of curb" being assigned different regulations, especially since new regulations may be positioned to start/end at slightly different points along the curb due to sign or paint placement.
To mitigate the performance implications to re-fetching full Curb Zone information on each API call, we will build functionality into the API to avoid fetching the largest and most complex data fields; callers worried about performance can cache each zone's full data and only fetch new versions of that data when they see a brand new ID.
See the discussion here.
Per the scope for the first release of CDS, it is designed to stand alone and not reference MDS directly. Using parts of MDS now during pilot projects could add unnecessary complexity for implementors, and MDS was too far into its 1.2 release to add feature needed for the curb. However, we are aligning where possible now and in future releases. Here is what we are considering, in order of complexity:
- Name coherence (this release) - using the same endpoints, field names and data types where possible. Eg, policy endpoint, end_date, UUIDs
- Architectural alignment (this release) - structuring the endpoints and file formats to be similar. Eg, JSON structure
- Update MDS (next release) - change MDS to match what is needed in CDS. Eg, with policy rate, geographies, etc
- Reference MDS (next release) - directly reference parts of MDS. Eg, Policy, Geography, or Jurisdiction APIs
Part of MDS 2.0 will include a re-evaluation of the Policy API, and since it will be a major release, support for CDS needs can be added at that time. See the Issue to track this in detail for the next release.
The use of centimeter units allows integer (non-decimal) values for all measurements, clearer conversion from meters or feet, and alignment with MDS design principles to use the smallest reasonable integer units possible for fields (eg, milliseconds, cents, etc). See the discussion here.
For CDS APIs, the decision has been made for them all to be Pull for ease of implementation. This means an entity checks the endpoint on some regular basis, and sees what's new since their last check. The opposite of this is Push, which means things get sent as they happen to a consumer of the data, eg a city receiving events as they happen.
Pull is easier to implement in general. You can check as often as needed (eg 1/5/15/60 minutes) and can get old data up to a certain point in the past (eg 1/5/30 days). The downside is potentially lots of unchanging data returned each check, and you must hit and manage multiple sources, but these are not too difficult to manage.
Push is more complex since if your receiving system goes offline, you may miss data and then a Pull mechanism is needed any way to catch up. You have less endpoint hits/checks, less data, less credentials to manage, and its more real-time capable. But the downsides are if an endpoint goes offline, it could miss data, and sources will need success confirmation and resend data upon failures.
For the first CDS release, we are going to mimic MDS/GBFS structure for vehicle_type and propulsion_type, starting with what's in MDS/GBFS, but defining values as needed here in CDS. Later, we will align them more directly with the future MDS 2.0 release and next CDS release. This allows CDS to be flexible for pilots and bring the results back to MDS's next major release, which is focused on "modes" and could impact these values.
