Draft v1.1

.gitignore

@@ -0,0 +1 @@
+archive/*

AGENTS.MD

@@ -0,0 +1,97 @@
+# Working with the CDS OpenAPI Project
+
+This document describes how to collaborate with an AI agent (or human contributor) on the `cds-openapi` project.
+
+## Project Purpose
+
+This repository maintains an **OpenAPI 3.1 specification** for the [Curb Data Specification (CDS)](https://github.com/openmobilityfoundation/curb-data-specification), managed by the Open Mobility Foundation. The spec is hosted publicly via Stoplight and serves as an interactive API browser for implementers.
+
+## Repository Structure
+
+```
+cds-openapi/
+  APIs/
+    Curbs API.yaml        # Curb zones, areas, spaces, policies, objects
+    Events API.yaml       # Curb events and sensor status
+    Metrics API.yaml      # Sessions and aggregates
+  Shared Data Models/     # Reusable YAML schemas (curb_zone, curb_event, etc.)
+  Rest Responses/         # Common API response header schemas
+  toc.json                # Stoplight table of contents
+  .spectral.mjs           # Linting rules
+  .stoplight.json         # Stoplight platform config
+  V1.1_IMPLEMENTATION_PLAN.md  # Active implementation plan
+```
+
+## Branch Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Stable, latest released version |
+| `v1.0` | Frozen v1.0 spec |
+| `draft-v1.1` | Active development branch for v1.1 changes |
+
+Always work on the `draft-v1.1` branch (or a feature branch off it) when implementing v1.1 changes. Never push directly to `main`.
+
+## Upstream Spec Reference
+
+The authoritative CDS spec lives at https://github.com/openmobilityfoundation/curb-data-specification. When implementing changes:
+
+1. Treat the upstream repository's `main` branch as the source of truth for the latest CDS specification
+2. Always cross-reference the upstream spec text, not just PR summaries
+3. Before editing local OpenAPI files, verify the relevant field names, types, enums, descriptions, and required/optional status against upstream `main`
+4. When a discrepancy is found, label it explicitly as local drift, upstream ambiguity, or an inference
+5. The spec has three sections: `curbs/`, `events/`, `metrics/` — each with its own README
+6. The `general-information.md` and `data-types.md` files contain shared definitions
+
+## How to Make Changes
+
+### Workflow for each step in the implementation plan
+
+1. **Read the plan step** in `V1.1_IMPLEMENTATION_PLAN.md`
+2. **Read the upstream spec on `main`** for the relevant section to confirm exact field names, types, enums, descriptions, and required/optional status
+3. **Edit the YAML files** — maintain the existing style conventions:
+   - Use `$ref` for shared models rather than inline definitions
+   - Include `description` on every field
+   - Use `x-stoplight: id:` annotations if present on surrounding fields (Stoplight generates these)
+   - Keep `required` arrays up to date
+4. **Validate** — run the Spectral linter (`.spectral.mjs`) after all changes for the task. `spectral` is currently available in this environment, so validation should be performed before wrapping up work.
+5. **Update the plan** — use strikethrough in `V1.1_IMPLEMENTATION_PLAN.md` to mark completed items as work lands. Do not add status suffixes like `DONE`, `TODO`, or `Partial` to implementation-step headings.
+6. **Commit** — use the commit message suggested in the plan step, or a similar conventional-commit style message
+
+### Style conventions
+
+- File names: `snake_case.yaml` for shared models
+- Enum values: `snake_case`
+- UUID fields: `type: string, format: uuid`
+- Timestamps: `$ref: ./timestamp.yaml`
+- Geographic fields: `$ref` to `geoJSON_point.yaml`, `geoJSON_polygon.yaml`, or `geoJSON_linestring.yaml`
+- Arrays of references: `type: array` with `items: { $ref: ./some_model.yaml }`
+
+### Adding a new shared model
+
+1. Create the YAML file in `Shared Data Models/`
+2. Add a `$ref` from any model or API that uses it
+3. Add an entry to `toc.json` under the appropriate section
+4. Verify the `$ref` path is correct relative to the referencing file
+
+## Validation
+
+The project uses Spectral for OpenAPI linting:
+
+```bash
+spectral lint "APIs/*.yaml"
+```
+
+The `.spectral.mjs` config extends a remote Stoplight ruleset. `spectral` is currently available in this workspace and should be run after all changes are made. Always lint and fix any errors before committing. When a task adds or edits standalone shared model files, lint those touched files as well in addition to the API documents.
+
+## Key Gotchas
+
+- **$ref paths are relative** to the file containing the reference. API files use `../Shared Data Models/foo.yaml`; shared models use `./foo.yaml`.
+- **Spaces in file names**: `Curbs API.yaml` has a space — use URL encoding (`Curbs%20API.yaml`) in Markdown links but literal paths in `$ref`.
+- **toc.json** controls what appears in the Stoplight browser — new models won't show up until added here.
+- **x-stoplight IDs** are auto-generated by the Stoplight editor. When adding fields by hand, you can omit them and Stoplight will generate them later, or include them for consistency.
+- **501 responses** must be documented on all optional endpoints per the CDS spec pattern.
+
+## Implementation Plan
+
+The active plan for v1.1 work is in `V1.1_IMPLEMENTATION_PLAN.md`. Follow the phases and steps in order — they are sequenced so that schema dependencies are in place before API paths reference them.