Style Conventions

YAML File Format

When editing OpenAPI YAML files, follow these 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 auto-generates these)
• Keep required arrays up to date

Field Type 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

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.