This documents contains information to assist in creating a WZDx data feed, such as the feed format, business rules, and validation tools.
WZDx feeds are formatted according to the GeoJSON specification. The output of a WZDx feed is a GeoJSON document (a .geojson file) that contains a single GeoJSON FeatureCollection which includes information about the feed (see the FeedInfo Object) and a list of GeoJSON Features describing entities specific to the type of feed, such as work zones.
GeoJSON is the file format of choice because:
- It is a lightweight data exchange format.
- It is easy for humans to read and write.
- It is easy for machines to parse and generate.
- The format is designed to exchange spatial data, which is a primary goal of the Work Zone Data Working Group.
- It is an open specification and does not carry licensing burdens.
- GeoJSON formatted-data is published as text files, so there is a low technological burden of entry.
- GeoJSON validation, mapping, and visualization tools already exist and will ease adoption by producers and consumers.
WZDx defines the content and structure of several data feeds. Each feed is described by a single root object with many child objects. The output of a WZDx data feed is a GeoJSON file containing the feed object. WZDx defines the following feed objects:
- WZDxFeed Object: describes high-level information about work zone events ocurring on roadways (called "road events") that impact the characteristics of the roadway and involve a change from the default state (such as a lane closure). This is the original work zone data exchange feed and the only feed that WZDx defined until version 4.0.
- RoadRestrictionFeed Object: describes the location and details of restrictions on roadways.
- SwzDeviceFeed Object: describes information (location, status, live data) about field devices deployed on the roadway in work zones.
See the /spec-content/README.md for detailed information on all objects defined by WZDx.
The following business rules help assure a standardized and interpretable use of the WZDx specification. The specification describes the required structure and data fields to describe a work zone, whereas business rules are additional requirements for using the WZDx specification in a standard manner. Note that business rules are distinct from best practices in that the latter are suggestions and business rules are requirements that cannot be validated by the JSON schema.
- An event must be segmented into separate WorkZoneRoadEvents, RestrictionRoadEvents, or DetourRoadEvents when the value of a required property or lane object changes. A complex event should be linked together using the
relationshipproperty. - If the
lanesproperty on the WorkZoneRoadEvent or RestrictionRoadEvent is provided, it must include one entry for every lane in the road event. Providing lane information for only some of the lanes in a road event is not allowed. - A Lane
orderor TrafficSensorLaneDatalane_ordervalue of 1 must represent the left-most lane and an increase in 1 must represent moving a single lane to the right. - The
data_source_idvalue must match to thedata_source_idproperty of a FeedDataSource included within the same WZDx GeoJSON document on the WorkZoneRoadEvents, RestrictionRoadEvents, and DetourRoadEvents. - All dates and times must be expressed in UTC.
This is a working list of best practices for standing up a WZDx data feed assembled by the WZDx Technical Assistance Co-chairs. Please note that this list is not all encompassing; DOTs should consult with security experts for help with securing infrastructure components. Please note that these are best practices only; not requirements.
If the WZDx feed is set up as a REST Service endpoint, it is recommended that the only exposed endpoint in the REST service for the feed is a HTTP GET endpoint. If a provider wants to allow queries to the data using the request body rather than using URL parameters with a GET request, HTTP POST is also allowed. Exposing only a retrieval method and a post method will deter unauthorized users from attempting to delete or alter the existing WZDx feed provided. All WZDx endpoints should allow only read access. No public endpoint should be exposed that allows write access to the feed.
In order to secure data in transit from the WZDx feed to the recipient, building the data feed endpoint using a Secure Sockets Layer (SSL) certificate is highly recommended. This ensures that the connection between the host and the recipient is secure and that data received from the recipient can be trusted.
Though all DOTs have infrastructure capabilities to host a WZDx feed, it is recommended that the feed be cloud hosted on a trusted platform due to the following reasons:
- Security: Trusted cloud hosted providers such as Amazon Web Services, Google Cloud Platform, and Microsoft Azure all have hardened physical security as well as digital security best practices already in place.
- Dedicated Denial of Service (DDoS) Prevention: DDoS attacks remain a very common form of hacking that are still used today. Cloud providers have built solid solutions that can handle DDoS attacks and prevent downtime.
- Scalable: As WZDx feeds become more widely used, they may be hit much more frequently than other endpoints. Cloud hosting allows DOTs to easily scale to accommodate for more hits or usage of the endpoint.
- Load Balancing Solutions: Along with scaling physical hardware, load balancing allows DOTs the ability to scale the number of endpoints serving up WZDx data feeds.
DOTs should consider the sources that are being used to build the WZDx feeds and ensure that those systems are also following the same best practices listed as above. WZDx feeds should be built from reliable data received from the field and trusted sources of data.
The WZDx Specification defines a JSON schema for each feed (WZDx v2.0 and later) within the schemas directory. The repository contains schemas for the following feeds:
For a list of steps to take to make sure your data feed conforms to the specification and is ready to publish, follow the Self-Validation Checklist.
To validate data feeds and measure compliance with the v1.1 specification, the GSA/18F team developed a prototype data validation tool.