APX is an open, additive companion standard to APDS 4.1 (Alliance for Parking Data Standards / ISO TS 5206-1). One API that PARCS, LPR, tolling, permitting, and reservations vendors implement — adding what APDS deliberately leaves out, while reusing everything it defines.
Two tracks. The data elements and enumerations APX needs are proposed to APDS for its data model in the APX Data Specification (Overview, Information Model, Data Dictionary and Use Case Document, in the form of the APDS 4.1 documents). The API in this repository is APX's preferred implementation specification on top of APDS; it is not proposed for the data model. The APX Specification documents describe both tracks in the same form: everything the API defines, and everything APX asks APDS to add or change.
New here? Read the executive summary (shareable, non-technical), the complete API overview (every route + the reasoning, no APDS knowledge needed), the sample scenarios (real wire exchanges, story first), or the quickstart. Want to see it run? Open the simulator in your browser — every APX route, narrated demos, and the full vetting suite, nothing to install (about the simulator). PARCS vendor? Start with the PARCS Starter Profile — the minimum 26-endpoint surface, with a slim importable spec (spec/dist/apx-parcs.json).
Wherever APDS 4.1 already defines a route, schema, or convention, APX uses it
verbatim — the official apds-api-4.1.yaml is vendored unmodified (MIT,
checksum-guarded) and reused by $ref. A plain APDS 4.1 client works against
an APX implementation without changes. APX adds only what APDS lacks:
| Domain | What APX adds | Anchored on |
|---|---|---|
| Data profile | Full/Change updates, tombstones, cursor change feed | APDS native routes (/places, /sessions, /rates, /rights/*, /observations, /quotes) |
| Delivery fabric | HMAC-signed webhooks, normative retries, delivery ledger, SSE | APDS /webhooks + EventSubscription (superset-compatible) |
| Control | Command plane (vend gate, lost ticket, rate push, validations…), lane inquiry, device status; negotiated rates selected from deck tables flagged negotiable, applied to the one ticket in the lane with the selecting agent on the audit; ticket matching — open-session candidates by plate, phone, or credential and an agent-attributed matchTicket that closes the open ticket at the real fare |
SupplementalEquipment, HierarchyElementReference |
| Alerts | Alert lifecycle + open taxonomies | UserDefinedCodeList, Use Case C.2.2 exception vocabulary |
| Discovery | Credential-scoped capability documents | OAuth2 scopes + place grants |
| Accounts & payments | Balance lookup, take-payment, accounting write-back, payment history | RightHolder, Payment |
| LPR | Plate↔ticket cross-lookup with confidence + imagery; per-attribute confidence (plate, state, make, model, colour), alternate reads, plates read, plate face, movement, and server-derived lane travel for gateless wrong-way detection | Observation, Confidence, Image, VehicleAncillaryIdentification, VehicularAccess.accessType (4.1) |
| Reservations | Quote→book→amend→check-in conventions | Quote*, AssignedRight, PlannedUse |
| Permits | Pooled issuance, multi-vehicle credentials | RightSpecification, RightPool, Credential |
| Tolling | TollTransaction + dispute lifecycle (net-new) | Observation → pricing → Payment |
| Violations | Automated + guided enforcement: detection, review, notice/citation, appeal (net-new); eligibility check for handhelds; per-location enforcement policy (lawful notice methods, penalty caps, server-applied escalation) and posted-signage evidence | AssignedRight (eligibility), Observation/Image/Location (evidence), Payment (settlement), ep role |
| Validations | Merchant programs, instrument issuance, redemption ledger from every channel, closable billing statements, merchant scope | Contact/Organisation (merchant), Segment.validationId, Payment type validation, RateDiscount, RateTable.validation |
| Credentials | Keycard/fob/RFID/mobile lifecycle — issue, suspend, lost, revoke, replace — with media and deposits, access-event history; active records materialized onto the assigned right | CredentialAssigned, CredentialTypeEnum, AssignedRight, RightHolder |
| Valet | Custody with condition evidence (notes, damage entries, photos, acknowledgement), parked position and keys, retrieval queue with ETA from text/app/web/voice bot, staging, verified handback, customer scope (net-new) | Session (the stay), AssignedRight, Space, Contact, Payment |
| EV charging | The parking-side view: live charging-point status with camera bay-presence fusion (vehicle not plugged in, bay blocked), ChargingSession on the parking stay with OCPP-aligned state, idle after complete, cost and three settlement modes (one bill at exit), customer status scope; charger control via the command plane; OCPP/OCPI ids carried opaquely | ElectricChargingEquipment, ElectricChargingPoint, Connector, AuthenticationAndIdentificationEnum, Session, Space, Observation, Payment |
| Plate lists | Watch, scofflaw, allow, and enforcement-vehicle lists with per-place flags (alert on arrival, refuse service), their entries, and the change feed that keeps an edge copy current (Part 24) | |
| UI launch | A vendor's own screens, per module, opened for an agent with automatic login (one-time URL or signed token, 60 s, single use); everything done there comes back as the native APX record or a UiActionRecord with the fields the host asked for (Part 25) |
OAuth2 scopes + place grants, Command.agent, Part 17 AllowedAction |
| Site configuration | A location described from APX alone: a fixed list of equipment roles (gate, access door, ticket dispenser, reader, camera, intercom…) with make, model, versions, serial and MAC on every device; areas; cameras with what they look at and short-lived view links; comms points (intercom, dialer, posted number) with caller id and dialed number; escalation roles; typed ids in other systems; display records (which sign showed which message, for which stay); change notices (Part 26) | SupplementalEquipment, EquipmentTypeEnum, VehicularAccess, HierarchyElement, Period |
Extension identity follows the official APDS convention (Use Case §C.2.5):
apds-ext:apx:<class>@<version>.
| Path | Contents |
|---|---|
spec/openapi/ |
The standard — modular OpenAPI 3.1 (apx.yaml root; one directory per domain) |
spec/vendor/apds/4.1/ |
APDS 4.1 vendored verbatim (MIT) — never edited, checksum-guarded |
spec/registries/ |
UserDefinedCodeList registries (alert types, command types, device states, topics, conformance classes) |
docs/standard/ |
The written standard (normative, RFC 2119) |
docs/scenarios/ |
End-to-end sample scenarios with spec-validated wire payloads |
tools/ |
Spec tooling — lint/bundle configs, vendor integrity check, registry + example + scenario validators |
packages/simulator/ |
The APX simulator (non-normative) — a stateful server for every route in the bundle, with a browser UI, narrated demos, and the vetting suite; see its README and the demo runbook |
npm install
npm run vendor:check # verify vendored APDS artifacts are untouched
npm run spec:lint # Redocly lint (modular source)
npm run spec:bundle # produce spec/dist/apx-v1.{yaml,json}
npm run spec:style # Spectral APX conventions (bundled artifact)
npm test # all of the above + registry, profile, and example validation
npm run mock # Prism mock server on :4010 — schema-valid fake responses
npm run docs:build # assemble the documentation site into site/
npm run sim # the APX simulator with its UI on http://127.0.0.1:4100
npm run sim:web # build the in-browser simulator into site/simulator/Requires Node 20+. No Docker, no native modules.
Browsable docs are published from main to GitHub Pages:
https://rneubauer.github.io/apx/ is the landing page, listing every module
with a link to its section of the reference and to the part that governs it.
/reference.html is the full API reference, /parcs.html the PARCS starter
profile, and /apx-standard.md the whole written standard compiled into one
document. Served alongside them: the bundles at /apx-v1.yaml,
/apx-v1.json, and /apx-parcs.json, the code-list registries under
/registries/, and /edition.json, which pins by checksum exactly what
this edition comprises. /simulator/ is the
simulator, running entirely
in the browser: each visitor gets their own copy, and a reload starts over.
CI validates every push and PR; pull requests are additionally gated by an
oasdiff breaking-change check against the base branch's bundle.
Change process, ground rules, and merge gates: CONTRIBUTING.md. Version history: CHANGELOG.md.
v0.16.0 — complete v1 draft, vetted. All domains specified: data profile, delivery fabric, control, alerts, discovery, accounts & payments, LPR, reservations, permits, tolling, customer service & resolution, violations (enforcement), validation programs, credential lifecycle, valet, EV charging, plate lists, UI launch and site configuration, with display records, stay compliance and separate entry and exit grace. This repository contains the specification, the written standard, and a non-normative simulator for trying them out; production implementations live elsewhere.
MIT. Portions reference the APDS API Specification (MIT, © Alliance for Parking Data Standards).