|
| 1 | +# JSON Data Files |
| 2 | + |
| 3 | +This document describes the JSON data files used by the language service packages and how they are maintained. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The language service uses several JSON files containing schema definitions, webhook payloads, and other metadata. To reduce bundle size, these files are: |
| 8 | + |
| 9 | +1. **Optimized at generation time** — unused events are dropped, unused fields are stripped |
| 10 | +2. **Minified at build time** — whitespace is removed to produce `.min.json` files |
| 11 | + |
| 12 | +The source `.json` files are human-readable and checked into the repository. The `.min.json` files are generated during build and gitignored. |
| 13 | + |
| 14 | +## Files |
| 15 | + |
| 16 | +### languageservice |
| 17 | + |
| 18 | +| File | Description | |
| 19 | +|------|-------------| |
| 20 | +| `src/context-providers/events/webhooks.json` | Webhook event payload schemas for autocompletion | |
| 21 | +| `src/context-providers/events/objects.json` | Deduplicated shared object definitions referenced by webhooks | |
| 22 | +| `src/context-providers/events/schedule.json` | Schedule event context data | |
| 23 | +| `src/context-providers/events/workflow_call.json` | Reusable workflow call context data | |
| 24 | +| `src/context-providers/descriptions.json` | Context variable descriptions for hover | |
| 25 | + |
| 26 | +### workflow-parser |
| 27 | + |
| 28 | +| File | Description | |
| 29 | +|------|-------------| |
| 30 | +| `src/workflow-v1.0.json` | Workflow YAML schema definition | |
| 31 | + |
| 32 | +## Generation |
| 33 | + |
| 34 | +### Webhooks and Objects |
| 35 | + |
| 36 | +The `webhooks.json` and `objects.json` files are generated from the [GitHub REST API description](https://github.com/github/rest-api-description): |
| 37 | + |
| 38 | +```bash |
| 39 | +cd languageservice |
| 40 | +npm run update-webhooks |
| 41 | +``` |
| 42 | + |
| 43 | +This script: |
| 44 | +1. Fetches webhook schemas from the GitHub API description |
| 45 | +2. **Validates** all events are categorized (fails if new events are found) |
| 46 | +3. **Drops** events that aren't valid workflow triggers (see [Dropped Events](#dropped-events)) |
| 47 | +4. **Strips** unused fields like `description` and `summary` (see [Stripped Fields](#stripped-fields)) |
| 48 | +5. **Deduplicates** shared object definitions into `objects.json` |
| 49 | +6. Writes the optimized, pretty-printed JSON files |
| 50 | + |
| 51 | +### Handling New Webhook Events |
| 52 | + |
| 53 | +When GitHub adds a new webhook event, the script will fail with an error like: |
| 54 | + |
| 55 | +``` |
| 56 | +ERROR: New webhook event(s) detected! |
| 57 | +
|
| 58 | +The following events are not categorized: |
| 59 | + - new_event_name |
| 60 | +
|
| 61 | +Action required: |
| 62 | + 1. Check if the event is a valid workflow trigger |
| 63 | + 2. Add the event to DROPPED_EVENTS or KEPT_EVENTS |
| 64 | +``` |
| 65 | + |
| 66 | +**To resolve:** |
| 67 | + |
| 68 | +1. Check [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows) |
| 69 | + |
| 70 | +2. Edit `languageservice/script/webhooks/index.ts`: |
| 71 | + - Add to `KEPT_EVENTS` if it's a valid workflow trigger |
| 72 | + - Add to `DROPPED_EVENTS` if it's GitHub App or API-only |
| 73 | + |
| 74 | +3. Run `npm run update-webhooks` and commit the changes |
| 75 | + |
| 76 | +#### Viewing Full Unprocessed Data |
| 77 | + |
| 78 | +To see all available fields and events before optimization: |
| 79 | + |
| 80 | +```bash |
| 81 | +npm run update-webhooks -- --all |
| 82 | +``` |
| 83 | + |
| 84 | +This generates `webhooks.all.json` and `objects.all.json` (gitignored) containing the complete unprocessed data from the GitHub API. |
| 85 | + |
| 86 | +### Other Files |
| 87 | + |
| 88 | +The other JSON files (`schedule.json`, `workflow_call.json`, `descriptions.json`, `workflow-v1.0.json`) are manually maintained. |
| 89 | + |
| 90 | +## Minification |
| 91 | + |
| 92 | +At build time, all JSON files are minified (whitespace removed) to produce `.min.json` versions: |
| 93 | + |
| 94 | +```bash |
| 95 | +npm run minify-json |
| 96 | +``` |
| 97 | + |
| 98 | +This runs automatically via `prebuild` and `pretest` hooks, so you don't need to run it manually. |
| 99 | + |
| 100 | +The code imports the minified versions: |
| 101 | + |
| 102 | +```ts |
| 103 | +import webhooks from "./events/webhooks.min.json" |
| 104 | +``` |
| 105 | + |
| 106 | +## CI Verification |
| 107 | + |
| 108 | +CI verifies that generated source files are up-to-date: |
| 109 | + |
| 110 | +1. Runs `npm run update-webhooks` to regenerate webhooks.json and objects.json |
| 111 | +2. Checks for uncommitted changes with `git diff --exit-code` |
| 112 | + |
| 113 | +The `.min.json` files are generated at build time and are not committed to the repository. |
| 114 | + |
| 115 | +If the build fails, run `cd languageservice && npm run update-webhooks` locally and commit the changes. |
| 116 | + |
| 117 | +## Dropped Events |
| 118 | + |
| 119 | +Webhook events that aren't valid workflow `on:` triggers are dropped (e.g., `installation`, `ping`, `member`, etc.). These are GitHub App or API-only events. |
| 120 | + |
| 121 | +See `DROPPED_EVENTS` in `script/webhooks/index.ts` for the full list. |
| 122 | + |
| 123 | +## Stripped Fields |
| 124 | + |
| 125 | +Unused fields are stripped to reduce bundle size. For example: |
| 126 | + |
| 127 | +```json |
| 128 | +// Before (from webhooks.all.json) |
| 129 | +{ |
| 130 | + "type": "object", |
| 131 | + "name": "issue", |
| 132 | + "in": "body", |
| 133 | + "description": "The issue itself.", |
| 134 | + "isRequired": true, |
| 135 | + "childParamsGroups": [...] |
| 136 | +} |
| 137 | + |
| 138 | +// After (webhooks.json) |
| 139 | +{ |
| 140 | + "name": "issue", |
| 141 | + "description": "The issue itself.", |
| 142 | + "childParamsGroups": [...] |
| 143 | +} |
| 144 | +``` |
| 145 | + |
| 146 | +Only `name`, `description`, and `childParamsGroups` are kept — these are used for autocompletion and hover docs. |
| 147 | + |
| 148 | +To compare all fields vs stripped, run `npm run update-webhooks -- --all` and diff the `.all.json` files against the regular ones. |
| 149 | + |
| 150 | +See `EVENT_ACTION_FIELDS` and `BODY_PARAM_FIELDS` in `script/webhooks/index.ts` to modify what gets stripped. |
0 commit comments