The Policy API endpoints are intended to be implemented by regulatory agencies and consumed by mobility providers. Providers query the Policy API to get information about local rules that may affect the operation of their mobility service or which may be used to determine compliance.
This specification describes the digital relationship between mobility as a service providers and the agencies that regulate them. The Policy API communicates municipal policies (such as as vehicle deployment caps and speed limits) in a clear, consistent manner.
The following information applies to all policy API endpoints.
The goal of the Policy API specification is to enable agencies to create, revise, and publish machine-readable policies, as sets of rules for individual and collective device behavior exhibited by both mobility as a service providers and riders / users. Examples of policies include:
- City-wide and localized caps (e.g. "Minimum 500 and maximum 3000 scooters within city boundaries")
- Exclusion zones (e.g. "No scooters are permitted in this district on weekends")
- Cap allowances (e.g. "Up to 500 additional scooters are permitted near train stations")
- Speed-limit restrictions (e.g. "15 mph outside of downtown, 10 mph downtown")
- Idle-time and disabled-time limitations (e.g. "5 days idle while rentable, 12 hours idle while unrentable, per device")
- Trip fees and subsidies (e.g. "A 25 cent fee applied when a trip ends downtown")
The machine-readable format allows Providers to obtain policies and compute compliance where it can be determined entirely by data obtained internally, and know what data is required from them and provided to them.
See the Policy Examples for ways Policy can be implemented.
The Policy endpoints should be made public. Authorization is not required.
The publishing agency should establish beforehand and communicate to providers how frequently the Policy endpoints are expected to change, how often they should be polled to get the latest information, and expectations around emergency updates.
Published policies, like geographies, should be treated as immutable data. Obsoleting or otherwise changing a policy is accomplished by publishing a new policy with a field named prev_policies, a list of UUID references to the policy or policies superseded by the new policy.
To update a policy, create a new policy with the new rules rules, and list the now updated policy id in prev_policies.
To revoke or end a policy, create a new policy with empty rules, and list the ended policy id in prev_policies.
Policy APIs must handle requests for specific versions of the specification from clients.
Policies shall be published by regulatory bodies or their authorized delegates as JSON objects. These JSON objects shall be served by either flat files or via REST API endpoints. In either case, policy data shall follow the schema outlined below.
Policies typically refer to one or more associated geographies. Geographic information is obtained from the MDS Geography API. Each policy and geography shall have a unique ID (UUID).
Geographical data shall be represented as GeoJSON Feature objects. No part of the geographical data should be outside the municipality boundary.
Policies should be re-fetched whenever:
- a policy expires (via its
end_date), or - at an interval specified by the regulatory body, e.g. "daily at midnight".
Flat files have an optional end_date field that will apply to the file as a whole.
Among other use-cases, configuring a REST API allows an Agency to:
- Dynamically adjust caps
- Set Provider specific policies
- Adjust other attributes in closer to real time
- Enumerate when policies are set to change
Responses must set the Content-Type header, as specified in the versioning section.
The response to a client request must include a valid HTTP status code defined in the IANA HTTP Status Code Registry.
See the Responses section for information on valid MDS response codes and the Error Messages section for information on formatting error messages.
Endpoint: /policies/{policy_id}
Method: GET
Schema: See mds-openapi repository for schema.
Authorization: public
data Payload: { "policies": [] }, an array of objects with the structure outlined below.
Path Parameters:
| Path Parameter | Type | Required / Optional | Description |
|---|---|---|---|
policy_id |
UUID | Optional | If provided, returns one policy object with the matching UUID; default is to return all policy objects. |
Query Parameters:
| Query Parameter | Type | Required / Optional | Description |
|---|---|---|---|
policy_id |
UUID | Optional | If provided, returns one policy object with the matching UUID; default is to return all policy objects. |
start_date |
timestamp | Optional | Beginning date of the queried time range; the default value is the request time |
end_date |
timestamp | Optional | Ending date of the queried time range; the default value is null, which captures all policies that are effective in the future |
start_date and end_date are only considered when no id parameter is provided. They should return any policy whose effectiveness overlaps with or is contained with this range. Suppose there's a policy with a start_date of 1/1/21 and end_date of 1/31/21. Assuming an end_date that is null, 12/1/20 and 1/5/21 start_dates will return the policy, but 2/10/21 wouldn't. Assuming a start_date parameter of say, 11/1/20, then an end_date of 12/1/20 wouldn't return the policy, but 1/5/21 and 2/10/21 would. Lastly, a start_date of 1/5/21 and end_date of 1/6/21 would also return the policy. Please note also that while dates in the format MM:DD:YY are being used here, start_date and end_date must be numbers representing milliseconds since the Unix epoch time.
Policies will be returned in order of effective date (see schema below), with pagination as in the agency and provider specs.
provider_id is an implicit parameter and will be encoded in the authentication mechanism, or a complete list of policies should be produced. If the Agency decides that Provider-specific policy documents should not be shared with other Providers (e.g. punitive policy in response to violations), an Agency should filter policy objects before serving them via this endpoint.
Possible HTTP Status Codes: 200, 400 (with parameter), 404, 406, 500
See Responses, Bulk Responses, and schema for details.
Deprecated: see the Geography API for the current home of this endpoint.
Endpoint: /requirements/
Method: GET
Beta feature: No (as of 2.0.0).
Authorization: public
Schema: See mds-openapi repository for schema.
data Payload: { requirements: [] }, JSON objects that follow the schema outlined here.
See Policy Requirements Examples for how this can be implemented.
Possible HTTP Status Codes: 200, 404, 406, 500
See Responses, Bulk Responses, and schema for details.
To use flat files, policies shall be represented in two (2) files:
policies.jsonin Policy APIgeographies.jsonin Geography API
The files shall be structured like the output of the REST endpoints above.
The publishing agency should establish and communicate to providers how frequently these files should be polled.
The last_updated field in the payload wrapper should be set to the time of publishing a revision, so that it is simple to identify a changed file.
Possible HTTP Status Codes: 200, 404, 406, 500
See Responses, Bulk Responses, and schema for details.
{
"version": "2.0.0",
"last_updated": 1570035222868,
"end_date": 1570035222868,
"policies": [
{
// policy JSON 1
},
{
// policy JSON 2
}
]
}The optional end_date field applies to all policies represented in the file.
{
"version": "2.0.0",
"last_updated": 1570035222868,
"geographies": [
{
// GeoJSON Feature 1
},
{
// GeoJSON Feature 2
}
]
}All response fields must use lower_case_with_underscores.
Response bodies must be a UTF-8 encoded JSON object and must minimally include the MDS version, a timestamp indicating the last time the data was last_updated, and a data payload:
{
"version": "x.y.z",
"last_updated": 1570035222868,
// endpoint/file specific payload
}See the Endpoints below for information on their specific schema, and the mds-openapi repository for full details and interactive documentation.
Before publishing a new Policy document, the document should be validated against the schema to ensure it has the correct format and fields.
An individual Policy object is defined by the following fields:
| Name | Type | Required / Optional | Description |
|---|---|---|---|
name |
String | Required | Name of policy |
mode_id |
Mode | Required | Mode this rule should apply, see MDS mode list for options. Default micromobility for backwards compatibility (this default will likely be removed in a subsequent MDS release) |
policy_id |
UUID | Required | Unique ID of policy |
provider_ids |
UUID[] | Optional | Providers for whom this policy is applicable; empty arrays and null/absent implies all Providers. See MDS provider list. |
description |
String | Required | Description of policy |
currency |
String | Optional | An ISO 4217 Alphabetic Currency Code representing the currency of all Rules with a rate_amount. |
start_date |
timestamp | Required | Beginning date/time of policy enforcement. In order to give providers sufficient time to poll, start_date must be at least 20 minutes after published_date. |
end_date |
timestamp | Optional | End date/time of policy enforcement |
published_date |
timestamp | Required | Timestamp that the policy was published |
prev_policies |
UUID[] | Optional | Unique IDs of prior policies replaced by this one |
rules |
Rule[] | Required | List of applicable Rule objects |
An individual Rule object is defined by the following fields:
| Name | Type | Required / Optional | Description |
|---|---|---|---|
name |
String | Required | Name of rule |
rule_id |
UUID | Required | Unique ID of the rule |
rule_type |
enum | Required | Type of policy (see Rule Types) |
geographies |
UUID[] | Required | List of Geography UUIDs (non-overlapping) specifying the covered geography |
states |
{ state: event[] } |
Required | Vehicle state to which this rule applies. Optionally provide a list of specific vehicle events as a subset of a given status for the rule to apply to. An empty list or null/absent defaults to "all". |
rule_units |
enum | Conditionally Required | Measured units of policy (see Rule Units) |
accessibility_options |
AccessibilityOption[] | Applicable vehicle accessibility options, default any (or none) | |
vehicle_types |
vehicle_type[] |
Optional | Applicable vehicle types, default "all". |
propulsion_types |
propulsion_type[] |
Optional | Applicable vehicle propulsion types, default "all". |
minimum |
integer | Optional | Minimum value, if applicable (default 0) |
maximum |
integer | Optional | Maximum value, if applicable (default unlimited) |
inclusive_minimum |
boolean | Optional | Whether the rule minimum is considered in-bounds (default true) |
inclusive_maximum |
boolean | Optional | Whether the rule maximum is considered in-bounds (default true) |
rate_amount |
integer | Optional | Amount of the rate (see Rate Amounts) |
rate_recurrence |
enum | Optional | Recurrence of the rate (see Rate Recurrences) |
rate_applies_when |
enum | Optional | Specifies when a rate is applied to a rule (see Rate Applies When) (defaults to out_of_bounds) |
start_time |
ISO 8601 time hh:mm:ss |
Optional | Beginning time-of-day when the rule is in effect (default 00:00:00). |
end_time |
ISO 8601 time hh:mm:ss |
Optional | Ending time-of-day when the rule is in effect (default 23:59:59). |
days |
day[] | Optional | Days ["sun", "mon", "tue", "wed", "thu", "fri", "sat"] when the rule is in effect (default all) |
messages |
{ String:String } |
Optional | Message to rider user, if desired, in various languages, keyed by language tag (see Messages) |
value_url |
URL | Optional | URL to an API endpoint that can provide dynamic information for the measured value (see Value URL) |
| Name | Description |
|---|---|
count |
Fleet counts based on regions. Rule minimum/maximum refers to number of devices in Rule Units. |
time |
Individual limitations or fees based upon time spent in one or more vehicle states. Rule minimum/maximum refers to increments of time in Rule Units. |
speed |
Global or local speed limits. Rule minimum/maximum refers to speed in Rule Units. |
user |
Information for users, e.g. about helmet laws. Generally can't be enforced via events and telemetry. |
| Name | Rule Types | Description |
|---|---|---|
seconds |
time |
Seconds |
minutes |
time |
Minutes |
hours |
time |
Hours |
days |
time |
Days |
mph |
speed |
Miles per hour |
kph |
speed |
Kilometers per hour |
devices |
count |
Devices |
Rule type user has no associated Rule units; rule_units is not required when the Rule type is user.
Rate-related properties can currently be specified on all rule types except user, i.e. any rule that can be measured.
Beta feature: No (as of 2.0.0).
The amount of a rate applied when this rule applies, if applicable (default zero). A positive integer rate amount represents a fee, while a negative integer represents a subsidy. Rate amounts are given in the currency defined in the Policy.
Rate recurrences specify how a rate is applied – either once, or periodically according to a time_unit specified using Rule Units. A time_unit refers to a unit of time as measured in local time for the jurisdiction – a day begins at midnight local time, an hour begins at the top of the hour, etc.
| Name | Description |
|---|---|
once_on_match |
Rate is applied once when a vehicle transitions into a matching status from a non-matching status. |
once_on_unmatch |
Rate is applied once a vehicle transitions out of a matching status to a non-matching status. |
each_time_unit |
During each time_unit, rate is applied once to vehicles entering or remaining in a matching status. Requires a time_unit to be specified using rule_units. |
per_complete_time_unit |
Rate is applied once per complete time_unit that vehicles remain in a matching status. Requires a time_unit to be specified using rule_units. |
The rate_applies_when field specifies when a rate should be applied to an event or count,
e.g. is it when the event is within the Rule bounds or when it is outside?
It defaults to out_of_bounds.
The rate_applies_when field may take the following values:
| Name | Description |
|---|---|
in_bounds |
Rate applies when an event or count is within the rule minimum and maximum |
out_of_bounds |
Rate applies when an event or count is outside of the rule minimum and maximum |
Some Policies as established by the Agency may benefit from rider communication. This optional field contains a map of languages to messages, to be shown to the user.
Language identifier values will be per BCP 47.
Example for a decreased speed-limit rule for Venice Beach on weekends:
"messages": {
"en-US": "Remember to stay under 10 MPH on Venice Beach on weekends!",
"es-US": "¡Recuerda mantener por debajo 10 millas por hora en Venice Beach los fines de semana!"
},An Agency may wish to provide dynamic or global rules, e.g.
"Within 300 yards of the stadium, 1000 total extra scooters may be deployed, across all Provider(s)."
In this case, compliance is not computable from the information available to a single Provider. The Agency may provide an endpoint to get the current count of vehicles in the service-area, so that individual Providers could decide whether adding some number to those present is allowed.
The payload returned from a GET request to the value_url will have the following immutable fields:
| Name | Type | Required / Optional | Description |
|---|---|---|---|
value |
integer | Required | Value of whatever the rule measures |
timestamp |
timestamp | Required | Timestamp the value was recorded |
policy_id |
UUID | Required | Relevant policy_id for reference |
Rules, being in a list, are ordered most specific to most general. E.g. an "earlier" rule (lower list index) would take precedence over a "later" rule (higher list index).
Rules are a form of pattern matching; conditions under which a given rule is "met" are specified, and a vehicle (or series of vehicles) may match with that rule or set of rules.
If a vehicle is matched with a rule, then it will not be considered in the subsequent evaluation of rules within a given policy. This allows for expressing complex policies, such as a layer of "valid" geographies in an earlier rule, with overarching "invalid" geographies in later rules.
The internal mechanics of ordering are up to the Policy editing and hosting software.
A public agency's Policy program Requirements endpoint enumerates all of the parts of MDS, CDS, GBFS, and other specifications that an agency requires from providers for certain programs, including APIs, endpoints, and optional fields, as well as information for providers about the APIs the agency is hosting. The program requirements are specific to the needs and use cases of each agency, and ensure there is clarity on what data is being asked for in operating policy documents from providers, reducing the burden on both. This also allows additional public transparency and accountability around data requirements from agencies, and encourages privacy by allowing agencies to ask for only the data they need.
Requirements can also be used to define a scaled-down MDS implementation in situations where an agency has more limited regulatory goals, has legal limitations on the types of data they can collect, or wants to use a lightweight version of MDS for a pilot project or other experiment where aspects of a full MDS implementation would be irrelevant or unnecessary.
See Policy Requirements Examples for ideas on how this can be implemented.
This endpoint is not authenticated (ie. public), and allows the discovery of other public endpoints within Geography, Policy, and Jurisdiction. The agency can host this as a file or dynamic endpoint on their servers, on a third party server, or the OMF can host on behalf of an agency in the agency program requirements repo. See this hosting guidance document for more information. This requirements file can be referenced directly in an agency's operating permit/policy document when discussing program data requirements, and updated digitally as needed. To be compliant with MDS you must obtain an agency_id and list your public URL in agencies.csv, per our guidance document.
The OMF recommends updating the Requirements feed no more than monthly, and you may specify your expected timeframe with the max_update_interval in the metadata section so providers have some idea of how often to check the feed. More specifically the OMF recommends giving the following notice to providers: 1 month for optional field additions, 3 months for endpoint/API changes/additions, 3 months for new minor releases, and 4 months for major releases. You should also communicate these future changes ahead of time with the start_date field. Finally, the OMF recommends any changes need to be part of a discussion between agencies and affected providers.
If you are upgrading to a new MDS version, it is recommended to create a new requirements file at a new URL, since field names and available options may have changed. To make this more obvious, the MDS version number could be part of your URL, e.g. "https://mds.cityname.gov/requirements/1.2.0".
When requirements are updated within the same MDS version, in the metadata section, increment the file_version value by one and update the last_updated timestamp. Though not required, you may choose to use the start_date and end_date fields in the programs section to keep retired requirements accessible. We also recommend hosting your requirements file in a location that has a publicly-accessible version history, like GitHub or Bitbucket, or keeping previous versions accessible with a versioned URL, e.g. "https://mds.cityname.gov/requirements/1.2.0/v3".
An agency's program Requirements endpoint contains a number of distinct parts, namely metadata, program definitions, and data specs (with sub sections on relevant required APIs).
{
"metadata": {
// metadata fields per the "Requirement Metadata" section
},
"programs" [
{
"description" : "[PROGRAM DESCRIPTION]",
"provider_ids": [
// provider id array
],
"vehicle_types": [
// optional vehicle_type array
],
"start_date": [timestamp],
"end_date": [timestamp],
"required_data_specs": [
{
"data_spec_name": "[NAME OF DATA SPEC]",
"version": "[VERSION NUMBER]",
"required_apis": [
{
"api_name" : "[API NAME]": {
// Data spec endpoints, urls, optional fields
}
]
}
},
// other data specs per the "Requirement Data Specs" section
]
},
// other MDS versions per the "Requirement MDS Version" section
}
}| Name | Type | Required / Optional | Description |
|---|---|---|---|
metadata |
JSON | Required | Requirement Metadata object. |
programs |
Array | Required | Array of Requirement Programs data. |
Contains metadata applicable to the agency and at the top of its Requirement data feed in the metadata section.
{
"metadata": {
"mds_release": "[TEXT]",
"file_version": "[INTEGER]",
"last_updated": "[TIMESTAMP]",
"max_update_interval": "[DURATION]",
"agency_id": "[UUID]",
"agency_name": "[TEXT]",
"agency_timezone": "[TIMEZONE]",
"agency_language": "[TEXT]",
"agency_currency": "[TEXT]",
"agency_website_url": "[URL]"
"url": "[URL]"
},
"mds_versions" [
// Requirement MDS Versions
]
}| Name | Type | Required / Optional | Description |
|---|---|---|---|
mds_release |
text | Required | Release of MDS that the requirements data feed aligns to, based on official MDS releases. E.g. "1.2.0" |
file_version |
integer | Required | Version of this file. Increment 1 with each modification. See version tracking for details. E.g. "3" |
last_updated |
timestamp | Required | When this file version was last updated. See version tracking for details. E.g. "1611958740" |
max_update_interval |
duration | Required | The expected maximum frequency with which this file could be updated. ISO 8601 duration. E.g. "P1M" |
agency_id |
UUID | Required | UUID of the agency this file applies to. Must come from agencies.csv file, per guidance. E.g. "737a9c62-c0cb-4c93-be43-271d21b784b5" |
agency_name |
text | Required | Name of the agency this file applies to. E.g. "Louisville Metro" |
agency_timezone |
timezone | Required | TZ Database Name used for dates and times in Requirements and across all MDS endpoints. E.g. "America/New_York" |
agency_language |
text | Required | An IETF BCP 47 language code, used across all MDS endpoints. E.g. "en-US" |
agency_currency |
text | Required | Currency used for all monetary values across all MDS endpoints. E.g. "USD" |
agency_website_url |
URL | Required | URL of the agency's general transportation page. E.g. "https://www.cityname.gov/transportation/" |
url |
URL | Required | URL of this file. Must be added to agencies.csv, per guidance. E.g. "https://mds.cityname.gov/requirements/1.2.0" |
Contains information about an agency's programs, with links to policy documents, and a list of providers and data specs/APIs/endpoints/fields that the program applies to over a certain time frame in its Requirement data feed in the required_data_specs section.
Unique combinations for data specs, specific providers, vehicle types, policies, and dates (past, current, or future) can be defined. For example an agency can define MDS version 1.2.0 and GBFS 2.2 for Provider #1 in a pilot with beta endpoints and optional fields, MDS version 1.2.0 for other providers without beta features starting a month from now, and MDS version 1.1.0 for Provider #2 with docked bikeshare.
// ...
"programs": [
{
"description" : "[PROGRAM DESCRIPTION]",
"program_website_url": "[URL]",
"program_document_url": "[URL]",
"provider_ids": [
"[PROVIDER UUID]",
// ...
],
"vehicle_types": [
"[vehicle_type]",
// ...
],
"start_date": [timestamp],
"end_date": [timestamp],
"required_data_specs" [
{
// Required Data Specs array
},
// other data specs
]
}
]
// ...| Name | Type | Required / Optional | Description |
|---|---|---|---|
description |
text | Required | Simple agency program description of this combination of MDS, providers, vehicles, and time frame. |
program_website_url |
URL | Required | URL of the agency's transportation policy page. E.g. "https://www.cityname.gov/transportation/shared-devices.htm" |
program_document_url |
URL | Optional | URL of the agency's operating permit rules that mention data requirements. E.g. "https://www.cityname.gov/mds_data_policy.pdf" |
provider_ids |
UUID[] | Required | Array of provider UUIDs that apply to this group the requirements |
vehicle_type |
Enum | Optional | Array of Vehicle Types that apply to this requirement. If absent it applies to all vehicle types. |
start_date |
timestamp | Required | Beginning date/time of requirements |
end_date |
timestamp | Required | End date/time of requirements. Can be null. Keep data at least one year past end_date before removing. |
required_data_specs |
Array | Required | Array of required Data Specs |
For each combination of items in a program, you can specify the data specs, APIs, endpoints, and optional fields that are required per your agency's program policies. This is an array within the Requirement MDS Versions mds_apis section in the Requirement data feed.
// ...
"required_data_specs": [
{
"data_spec_name": "[DATA SPEC NAME]",
"version": "[VERSION NUMBER]",
"mode_id": "[MODE SHORTNAME]",
"required_apis": [
{
// Required APIs array
}
],
"available_apis": [
{
// Available APIs array
}
]
},
// other data specs
]
// ...| Name | Type | Required / Optional | Description |
|---|---|---|---|
data_spec_name |
Enum | Required | Name of the data spec required. Supported values are: 'MDS', 'CDS' 'GBFS'. Others like GOFS, GTFS, TOMP-API, etc may also be referenced now by agencies and officially standardized here in the future -- leave your feedback on this issue. |
version |
Text | Required | Version number of the data spec required. E.g. '1.2.0' |
mode_id |
Text | Optional | The mode list shortname for MDS. E.g. 'passenger-services' |
required_apis |
Array | Conditionally Required | Name of the Requirement APIs that need to be served by providers. At least one API is required. APIs not listed will not be available to the agency. |
available_apis |
Array | Conditionally Required | Name of the Requirement APIs that are being served by agencies. Not applicable to GBFS. APIs not listed will not be available to the provider. |
For each data specification, you can specify which APIs, endpoints, and fields are required from providers, and which are available from your agency, and the use cases you need the data for.
An agency may require providers to serve optional APIs, endpoints, and fields that are needed for your agency's program. This is a required_apis array within the Requirement Data Specs section in the Requirement data feed.
Note: any APIs, endpoints, or fields that are required by a data specification are not to be listed, and are still required. Only optional items are enumerated here. You may however list disallowed_fields to exclude required fields. Optional APIs or endpoints should NOT be returned unless specified.
You may also show which APIs, endpoints, and fields your agency is serving to providers and the public. This is an available_apis array within the Requirement Data Specs section in the Requirement data feed.
// ...
"required_apis": [
{
"api_name" : "[API NAME]",
"required_endpoints": [
{
"endpoint_name" : "[ENDPOINT NAME]",
"required_fields": [
"[FIELD NAME]",
// other field names
],
"disallowed_fields": [
"[FIELD NAME]",
// other field names
]
},
// other endpoints
]
}
],
"available_apis": [
{
"api_name" : "[API NAME]",
"available_endpoints": [
{
"endpoint_name" : "[ENDPOINT NAME]",
"url": "[ENDPOINT URL]",
"available_fields": [
"[FIELD NAME]",
// other field names
]
},
// other endpoints
]
}
],
// other APIs in same data spec
"use_cases": [
{
"external_url": "[REFERENCE URL]",
"ids": ["1","2","3"]
},
// next external use case source
]
// ...| Name | Type | Required/Optional | Description |
|---|---|---|---|
api_name |
Text | Required | Name of the applicable API required. At least one API is required. APIs not listed will not be available to the agency. E.g. for MDS: 'provider', or 'agency'. For GBFS, this field is omitted since GBFS starts at the endpoint level. |
endpoint_name |
Text | Required | Name of the required endpoint under the API. At least one endpoint is required. E.g. for MDS 'provider': 'trips' |
use_cases |
Object with Array | Optional | The list of policy uses cases that this data standard's information covers for your program. Includes an external_url to a HTTP reference list or database (e.g. to the OMF Use Case Database), and an array of ids of each applicable use case (e.g. "OMF-MDS-31"). You may enumerate multiple external use case sources and ids. |
Provider Endpoints - Specific to the required_apis array
| Name | Type | Required/Optional | Description |
|---|---|---|---|
required_endpoints |
Array | Required | Array of optional endpoints required by the agency. At least one is required. Endpoints not listed will not be available to the agency. |
required_fields |
Array | Optional | Array of optional field names required by the agency. Can be omitted if no optional fields are required. Use dot notation for nested fields. See special notes below. |
disallowed_fields |
Array | Optional | Array of optional field names which must not be returned by in the endpoint, even if required in MDS. Use dot notation for nested fields. See special notes below. |
Agency Endpoints - Specific to the available_apis array
| Name | Type | Required/Optional | Description |
|---|---|---|---|
available_endpoints |
Array | Required | Array of endpoints provided by the agency. At least one is required. Endpoints not listed will not be available to the provider. |
url |
URL | Optional | Location of API endpoint url. Required if the API is unauthenticated and public, optional if endpoint is authenticated and private. E.g. "https://mds.cityname.gov/geographies/geography/1.1.0" |
available_fields |
Array | Optional | Array of optional field names provided by the agency. Can be omitted if none are required. Use dot notation for nested fields. See special notes below. |
Special notes about required_fields and disallowed_fields.
- All fields marked 'Required' in MDS are still included by default and should not be enumerated in
required_fields. They are not affected by the Requirements endpoint, unless explicitly listed indisallowed_fields. - Fields in MDS marked 'Required if available' are still returned if available, and are not affected by the Requirements endpoint, unless explicitly listed in
disallowed_fields. - If a 'Required' or 'Required if available' or 'Optional' field in MDS is listed in
disallowed_fields, those fields should not be returned by the provider in the endpoint. The field (and therefore its value) must be completely removed from the response. If used, schema validation may fail on missing required fields. - To reference fields that are lower in a hierarchy, use dot separated notation, where a dot between field names represents one nested level deeper into the data structure. E.g. 'gps.heading' or 'features.properties.rules.vehicle_type_id'.
- To require Geography Driven Events, simply include the
event_geographiesfield for either the Agency or Provider APIapi_name. Per how GDEs work,event_locationwill then not be returned, and thechanged_geographiesvehicle stateevent_typewill be used.