Skip to content

Commit f8dc295

Browse files
sanswaresansware
authored
chore: brand-name canon alignment, apex URL sweep, repo hygiene (#2)
Aligns the OpenAPI spec with brand canon (rename "TicketWave Access API" to "TicketWave API") and sweeps all www.ticketwavehq.com references to the apex ticketwavehq.com. Bumps spec version 1.0.0 to 1.0.1. Also adds standard repo hygiene: validate CI, CONTRIBUTING, CODE_OF_CONDUCT (Contributor Covenant 2.1), CODEOWNERS, SECURITY, a spec-discrepancy issue template, and a JSON-LD Organization schema in the README. No wire-format changes; downstream SDKs are unaffected.
1 parent e051294 commit f8dc295

9 files changed

Lines changed: 375 additions & 11 deletions

File tree

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* @sansware

‎.github/ISSUE_TEMPLATE/spec-discrepancy.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Spec discrepancy
2+
description: Report a difference between this OpenAPI spec and the live TicketWave API.
3+
title: "[spec-discrepancy] <short summary>"
4+
labels:
5+
- spec-discrepancy
6+
- triage
7+
assignees:
8+
- sansware
9+
body:
10+
- type: markdown
11+
attributes:
12+
value: |
13+
Thanks for filing a spec discrepancy. Please give us enough detail to reproduce.
14+
For security issues, **do not** use this form — see [`SECURITY.md`](../../SECURITY.md).
15+
- type: input
16+
id: operation
17+
attributes:
18+
label: Affected operation
19+
description: The `operationId` or path + method (e.g. `listEvents` or `GET /api/v1/events`).
20+
placeholder: GET /api/v1/events
21+
validations:
22+
required: true
23+
- type: input
24+
id: spec-version
25+
attributes:
26+
label: Spec version
27+
description: Value of `info.version` you tested against (e.g. `1.0.1`).
28+
placeholder: "1.0.1"
29+
validations:
30+
required: true
31+
- type: textarea
32+
id: request
33+
attributes:
34+
label: Request
35+
description: The HTTP method, path, headers (redact secrets), and body that you sent.
36+
render: http
37+
validations:
38+
required: true
39+
- type: textarea
40+
id: expected
41+
attributes:
42+
label: Expected response (per the spec)
43+
description: The schema / status code / shape that the spec promises.
44+
render: json
45+
validations:
46+
required: true
47+
- type: textarea
48+
id: actual
49+
attributes:
50+
label: Actual response
51+
description: What the live API actually returned. Include status code and body.
52+
render: json
53+
validations:
54+
required: true
55+
- type: textarea
56+
id: notes
57+
attributes:
58+
label: Additional notes
59+
description: Reproduction frequency, environment, anything else useful.
60+
validations:
61+
required: false
62+
- type: checkboxes
63+
id: confirmations
64+
attributes:
65+
label: Confirmations
66+
options:
67+
- label: I have checked the latest `openapi.yaml` on `main`.
68+
required: true
69+
- label: This is not a security vulnerability (if it is, I will email security@ticketwavehq.com instead).
70+
required: true

‎.github/workflows/validate.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Validate OpenAPI spec
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "openapi.yaml"
7+
- ".github/workflows/validate.yml"
8+
push:
9+
branches: [main]
10+
paths:
11+
- "openapi.yaml"
12+
- ".github/workflows/validate.yml"
13+
14+
jobs:
15+
validate:
16+
name: Lint + validate openapi.yaml
17+
runs-on: ubuntu-latest
18+
timeout-minutes: 5
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v4
22+
23+
- name: Setup Node.js
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: "20"
27+
28+
- name: Redocly lint
29+
run: npx --yes @redocly/cli@latest lint openapi.yaml
30+
31+
- name: swagger-cli validate
32+
run: npx --yes @apidevtools/swagger-cli@latest validate openapi.yaml

‎CHANGELOG.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,27 @@
11
# Changelog
22

3-
All notable changes to the TicketWave Access API OpenAPI specification are recorded in this file.
3+
All notable changes to the TicketWave API OpenAPI specification are recorded in this file.
44

55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) per the rules in [`README.md`](./README.md#versioning-policy).
66

7+
## [1.0.1] — 2026-06-28
8+
9+
Brand-name canon alignment + apex URL sweep. No wire-format changes.
10+
11+
### Changed
12+
13+
- `info.title` renamed from "TicketWave Access API" to "TicketWave API" to align with the canonical brand name (canon §3).
14+
- All `www.ticketwavehq.com` references swept to the apex `ticketwavehq.com`:
15+
- `info.contact.url`
16+
- `info.license.url`
17+
- `info.description` (api-keys URL)
18+
- `servers[1].url` (dashboard alias)
19+
- `components.securitySchemes.apiKey.description` (api-keys URL)
20+
- README License section
21+
- this CHANGELOG (footer reference below)
22+
23+
[1.0.1]: https://github.com/TicketWaveHQ/openapi-spec/releases/tag/v1.0.1
24+
725
## [1.0.0] — 2026-06-25
826

927
Initial public release of the spec.
@@ -29,7 +47,7 @@ Initial public release of the spec.
2947
- Bearer-token security scheme (`apiKey`) with `tw_live_*` token format documentation.
3048
- 14 tags grouping the surface by domain.
3149
- 64 component schemas covering requests, responses, and shared envelopes (`OffsetPagination`, `LimitPagination`, `Money`, `CustomerMasked`, `Tenant`, `Decision`, `Rule`, `Resource`, `Actor`, `Dispute`, `Override`, `Subscription`, `SystemEvent`, …).
32-
- Canonical server `https://access.ticketwavehq.com` listed first; dashboard alias `https://www.ticketwavehq.com` listed second (both resolve to the same deployment).
50+
- Canonical server `https://access.ticketwavehq.com` listed first; dashboard alias `https://ticketwavehq.com` listed second (both resolve to the same deployment).
3351
- Rate-limit guidance: 120 req/min/key on v1, 240 req/min/key on v2.
3452

3553
### Surface counts

‎CODE_OF_CONDUCT.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances
31+
of any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
[conduct@ticketwavehq.com](mailto:conduct@ticketwavehq.com).
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series of
86+
actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or permanent
93+
ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within the
113+
community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.1, available at
119+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120+
121+
Community Impact Guidelines were inspired by
122+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123+
124+
For answers to common questions about this code of conduct, see the FAQ at
125+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126+
[https://www.contributor-covenant.org/translations][translations].
127+
128+
[homepage]: https://www.contributor-covenant.org
129+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130+
[Mozilla CoC]: https://github.com/mozilla/diversity
131+
[FAQ]: https://www.contributor-covenant.org/faq
132+
[translations]: https://www.contributor-covenant.org/translations

‎CONTRIBUTING.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Contributing to TicketWave OpenAPI spec
2+
3+
Thank you for opening an issue or PR. This repository holds the single canonical OpenAPI 3.1 document for the TicketWave API. Because downstream SDKs and the official documentation viewer are generated from `openapi.yaml`, even small changes can ripple — please follow the rules below.
4+
5+
## Ground rules
6+
7+
- **One source of truth.** `openapi.yaml` is canonical. Do not split it.
8+
- **Semantic versioning.** Bump `info.version` per the rules in [`README.md`](./README.md#versioning-policy):
9+
- `patch` — documentation, descriptions, examples.
10+
- `minor` — additive only (new endpoints, optional fields, new enum values).
11+
- `major` — breaking changes. 30-day advance notice required.
12+
- **Changelog every release.** Add a `[x.y.z] — YYYY-MM-DD` block to [`CHANGELOG.md`](./CHANGELOG.md).
13+
- **Brand canon.** The product is the **TicketWave API** (not "Access API"). URLs use the apex `ticketwavehq.com` — no `www.` prefix.
14+
15+
## Local checks
16+
17+
```bash
18+
npx --yes @redocly/cli@latest lint openapi.yaml
19+
npx --yes @apidevtools/swagger-cli@latest validate openapi.yaml
20+
```
21+
22+
CI runs both on every PR via [`.github/workflows/validate.yml`](./.github/workflows/validate.yml).
23+
24+
## Filing a spec discrepancy
25+
26+
If the live API behaves differently from the spec, open an issue using the **"Spec discrepancy"** template at [`.github/ISSUE_TEMPLATE/spec-discrepancy.yml`](./.github/ISSUE_TEMPLATE/spec-discrepancy.yml). Include the request, the actual response, and the expected response per the spec.
27+
28+
## Pull request expectations
29+
30+
- Title: imperative mood, scoped (e.g. `feat(v2-rules): add ...`, `chore: ...`, `docs: ...`).
31+
- Description: what changed, why, and any version bump rationale.
32+
- One logical change per PR.
33+
- CI must be green.
34+
- Code-owner review per [`CODEOWNERS`](./.github/CODEOWNERS).
35+
36+
## Code of conduct
37+
38+
Participation is governed by [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
39+
40+
## Security
41+
42+
Do not file security issues here. See [`SECURITY.md`](./SECURITY.md) for the private disclosure channel.

‎README.md‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ A single [`openapi.yaml`](./openapi.yaml) describing two API namespaces:
2626
- 64 component schemas
2727
- 14 tags
2828

29-
All requests use bearer tokens of the form `tw_live_xxxxxxxxxxxxxxxx`, issued at <https://www.ticketwavehq.com/dashboard/settings/api-keys>. Tenant scoping is enforced server-side on every row — cross-tenant probes resolve to `404`, never `403`, so the surface cannot be used to enumerate other tenants.
29+
All requests use bearer tokens of the form `tw_live_xxxxxxxxxxxxxxxx`, issued at <https://ticketwavehq.com/dashboard/settings/api-keys>. Tenant scoping is enforced server-side on every row — cross-tenant probes resolve to `404`, never `403`, so the surface cannot be used to enumerate other tenants.
3030

3131
---
3232

@@ -96,4 +96,37 @@ Found a discrepancy between the spec and the live API? Open an issue here, or em
9696

9797
Apache License 2.0 — see [`LICENSE`](./LICENSE).
9898

99-
The TicketWave API itself is offered under the proprietary [TicketWave Public API Terms](https://www.ticketwavehq.com/terms); this OpenAPI document describing the API is Apache-2.0 so you can vendor, fork, generate clients from, and redistribute it freely.
99+
The TicketWave API itself is offered under the proprietary [TicketWave Public API Terms](https://ticketwavehq.com/terms); this OpenAPI document describing the API is Apache-2.0 so you can vendor, fork, generate clients from, and redistribute it freely.
100+
101+
---
102+
103+
## Organization metadata
104+
105+
```json
106+
{
107+
"@context": "https://schema.org",
108+
"@type": "Organization",
109+
"name": "TicketWave",
110+
"legalName": "TicketWave HQ Ltd",
111+
"url": "https://ticketwavehq.com",
112+
"logo": "https://ticketwavehq.com/logo.png",
113+
"description": "TicketWave is an events-and-access platform providing a public REST API for events, orders, and the access-decision engine.",
114+
"sameAs": [
115+
"https://github.com/TicketWaveHQ"
116+
],
117+
"contactPoint": [
118+
{
119+
"@type": "ContactPoint",
120+
"contactType": "developer support",
121+
"email": "developers@ticketwavehq.com",
122+
"url": "https://ticketwavehq.com/developers"
123+
},
124+
{
125+
"@type": "ContactPoint",
126+
"contactType": "security",
127+
"email": "security@ticketwavehq.com"
128+
}
129+
]
130+
}
131+
```
132+

0 commit comments

Comments
 (0)