openapi: 3.2.0
info:
  title: Jurisdictions API
  version: '2.0'
  summary: Providers query the Jurisdiction API to get information about agency jurisdictions.
  contact:
    url: https://github.com/openmobilityfoundation/mobility-data-specification
    name: Open Mobility Foundation
    email: info@openmobilityfoundation.org
  license:
    name: Creative Commons Attribution 4.0 International Public License
    url: https://github.com/openmobilityfoundation/mobility-data-specification/blob/main/LICENSE
  description: City and transportation agencies need to regulate mobility within their own jurisdictions.
tags:
- name: Jurisdictions
paths:
  /jurisdictions:
    parameters:
    - name: effective
      schema:
        $ref: '#/components/schemas/data-types_timestamp'
      in: query
      required: false
      description: See the state of all the Jurisdictions (i.e. which ones are effective) at that point in time. If not supplied, the default is to show only Jurisdictions that are currently in effect.
    get:
      operationId: get-jurisdictions
      description: Get all jurisdiction objects.
      summary: /jurisdictions
      responses:
        '200':
          description: Jurisdictions found.
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/response_version'
                - $ref: '#/components/schemas/response_last_updated'
                - type: object
                  description: Jurisdictions data payload
                  required:
                  - jurisdictions
                  properties:
                    jurisdictions:
                      type: array
                      items:
                        $ref: '#/components/schemas/jurisdiction'
        '400':
          description: Bad request.
        '404':
          description: Jurisdictions not found.
        '406':
          description: MDS version in Accept header is unsupported or invalid.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_error'
      tags:
      - Jurisdictions
  /jurisdictions/{jurisdiction_id}:
    parameters:
    - name: jurisdiction_id
      schema:
        $ref: '#/components/schemas/data-types_uuid'
      in: path
      required: true
      description: The `jurisdiction_id` of a jurisdiction object.
    - name: effective
      schema:
        $ref: '#/components/schemas/data-types_timestamp'
      in: query
      required: false
      description: See the version of the Jurisdiction that was in effect at that point in time.
    get:
      operationId: get-jurisdictions-jurisdiction_id
      description: Get the specified jurisdiction object.
      summary: /jurisdictions/{jurisdiction_id}
      responses:
        '200':
          description: Jurisdiction found.
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/response_version'
                - $ref: '#/components/schemas/response_last_updated'
                - type: object
                  description: Jurisdictions data payload
                  required:
                  - jurisdictions
                  properties:
                    jurisdictions:
                      type: array
                      minItems: 1
                      maxItems: 1
                      items:
                        $ref: '#/components/schemas/jurisdiction'
        '400':
          description: Bad request.
        '404':
          description: Jurisdiction not found.
        '406':
          description: MDS version in Accept header is unsupported or invalid.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_error'
      tags:
      - Jurisdictions
components:
  schemas:
    data-types_string:
      title: data-types/string
      description: A length-limited string type.
      examples:
      - ABC123
      maxLength: 255
      pattern: ^(.*)$
      type: string
      x-stoplight:
        id: 2vqv7166161kh
    data-types_version:
      title: data-type/version
      description: The version of MDS this data represents.
      type: string
      x-stoplight:
        id: bt49ntcbcuxbh
      pattern: ^2\.(\d|[1-9]\d+)\.(\d|[1-9]\d+)$
      examples:
      - 2.0.0
    response_error:
      title: response/error
      description: An error message for troubleshooting.
      type: object
      x-stoplight:
        id: 90yc58ni8u0ch
      required:
      - error
      - error_description
      - error_details
      properties:
        error:
          type: string
          description: Error message string.
        error_description:
          type: string
          description: Human readable error description (can be localized).
        error_details:
          type: array
          description: Human readable error description (can be localized).
          minItems: 1
          items:
            type: string
    response_version:
      title: response/version
      description: Response bodies must be a UTF-8 encoded JSON object and must minimally include the MDS `version`.
      type: object
      x-stoplight:
        id: ivd8jadc3rqf7
      required:
      - version
      properties:
        version:
          $ref: '#/components/schemas/data-types_version'
    data-types_uuid:
      title: data-types/uuid
      description: A UUID used to uniquely identity an object.
      type: string
      x-stoplight:
        id: np9kodwmy2kqa
      format: uuid
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      examples:
      - 3c9604d6-b5ee-11e8-96f8-529269fb1459
    data-types_mode:
      title: data-types/modes
      description: The modes supported in MDS.
      type: string
      x-stoplight:
        id: rjul1mcjyy8y2
      enum:
      - car-share
      - delivery-robots
      - micromobility
      - passenger-services
    data-types_timestamp:
      title: data-types/timestamp
      description: Integer milliseconds since Unix epoch.
      examples:
      - 1514764800000
      - 1681855703000
      minimum: 1514764800000
      multipleOf: 1
      type: number
      x-stoplight:
        id: vliol1hqlxw6y
    response_last_updated:
      title: response/last_updated
      type: object
      x-stoplight:
        id: z6u8eu7rlkd1j
      required:
      - last_updated
      properties:
        last_updated:
          $ref: '#/components/schemas/data-types_timestamp'
          description: Timestamp indicating the last time the data in this feed was updated.
    jurisdiction:
      title: models/jurisdiction
      description: 'A jurisdiction is:


        * A representation of an agency''s authority to the outside world

        * Human-readable name

        * Uniquely identified

        * Purview to make rules over physical boundaries and modal boundaries (e.g. a jurisdiction could be for taxis only)

        * A way of tracking revisions in an agency''s authority'
      type: object
      x-stoplight:
        id: 36fv404hae7bo
      required:
      - jurisdiction_id
      - agency_key
      - description
      - mode_ids
      - timestamp
      properties:
        jurisdiction_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: Unique ID of Jurisdiction. This field is immutable.
        agency_key:
          $ref: '#/components/schemas/data-types_string'
          description: A unique string key for the Jurisdiction. This field must also be immutable. Allows for easier management of Jurisdiction-based access control in JWTs.
        agency_name:
          $ref: '#/components/schemas/data-types_string'
          description: Human-readable agency name for display purposes.
        description:
          $ref: '#/components/schemas/data-types_string'
          description: Description of Jurisdiction.
        geography_id:
          $ref: '#/components/schemas/data-types_uuid'
          description: The unique ID of the geography covered by this Jurisdiction.
        mode_ids:
          type: array
          uniqueItems: true
          minItems: 1
          items:
            $ref: '#/components/schemas/data-types_mode'
        timestamp:
          $ref: '#/components/schemas/data-types_timestamp'
          description: Creation or update time of a Jurisdiction.
x-stoplight:
  id: 0c8f6q3fjyzbi
x-bundled-from: https://github.com/openmobilityfoundation/mds-openapi/blob/v2.0/reference/jurisdiction.yaml (commit 0c07bc3d294237dd41c6273f059efb11b8149c66); external $refs into ../models/ inlined under components.schemas, no other changes