feat: add workflow to validate OpenAPI schemas in reference/rest-api.json by treyhyde · Pull Request #64 · fulcrumapp/api

treyhyde · 2026-05-08T17:48:23Z

No description provided.

…json

…OpenAPI validation

Copilot

Pull request overview

Adds automation and guidance to keep the OpenAPI spec (reference/rest-api.json) valid and consistent during changes.

Changes:

Introduces a GitHub Actions workflow that validates reference/rest-api.json on PRs and pushes to v2.
Adds a Copilot skill document describing a process for syncing form-related schemas from upstream repos.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
.github/workflows/validate-openapi.yml	Adds CI validation for JSON syntax, RAW_BODY checks, external `$ref` checks, and `rdme openapi validate` on relevant changes.
.github/skills/sync-form-schema/SKILL.md	Adds a documented “skill” workflow for syncing form-related OpenAPI schemas from upstream sources.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pedrodotavila

Automated review: Good DevOps addition. The validation workflow will catch common OpenAPI spec issues (JSON syntax, RAW_BODY anti-patterns, external $ref paths). All CI checks passed.

osbornk · 2026-05-08T20:36:49Z

+All schemas live inline in `reference/rest-api.json` under `components.schemas`. The ones that
+map to the form model are:
+
+| OpenAPI Schema | Maps From |


This part concerns me. We state that the source of truth is in fulcrum-schema. But then we show this mapping. I am assuming that they are currently in sync. But now we have two different lists to maintain. I can see the LLM ignore a field type that has been deleted or ignoring fulcrum-schema because we already have a mapping here.

I would try just telling the LLM to check fulcrum-schema and describe what it should be looking for.

this is what we've done here.

osbornk · 2026-05-08T20:39:27Z

+| `fulcrumapp/fulcrum-schema` | `src/data-elements.js` | Complete list of element `type` enum values |
+| `fulcrumapp/fulcrum-schema` | `src/schema.js` | SQL column definitions per element — reveals what fields each type stores |
+| `fulcrumapp/fulcrum-schema` | `test/fixtures/form-v5.json` | Real form fixture — definitive JSON shape for all element types |
+| `fulcrumapp/fulcrum-core` | `src/form.js` | Form-level attributes (geometry_types, script, projects_enabled, etc.) |


Is fulcrum-core really the source of truth? We have to keep that in sync with the actual API.

I honestly have no idea what fulcrum-core does.

Dismissing automated approval per user request.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

+All schemas live inline in `reference/rest-api.json` under `components.schemas`. The current
+form model in that file is **not** split into per-element OpenAPI schemas such as
+`FormBaseElement`, `FormTextFieldElement`, or `FormChoiceFieldElement`, and `FormElement` is not
+currently documented there as a `oneOf` discriminated union. Do not update this skill as if that
+refactor has already happened.
+
+Use the schema names that actually exist in `reference/rest-api.json` today:
+
+| OpenAPI Schema | Maps From |
+|----------------|-----------|
+| `FormElement` | Primary form element schema. Keep its properties, enums, and required fields aligned with the upstream Fulcrum element model and fixture JSON. |
+| `StatusField` | Status field definition used by the current spec. Keep it aligned with the upstream status field shape. |
+| `StatusFieldChoice` | Status choice objects nested under status fields. Keep choice properties and enums aligned with upstream data. |
+
+If you find new upstream element-specific attributes in `fulcrum-schema` or `fulcrum-core`, first
+check whether they belong on the existing `FormElement` schema in `reference/rest-api.json`.
+Only document or edit per-element schemas after `reference/rest-api.json` has been explicitly
+refactored to introduce them.


+When syncing, treat the upstream fixture and element definitions as the source of truth for field
+names, required properties, enum values, and nested object shapes; then map those changes onto the
+actual current OpenAPI schemas listed above.
+| `FormHyperlinkFieldElement` | `HyperlinkField` |
+| `FormCalculatedFieldElement` | `CalculatedField` — expression, display, default_values |
+| `FormRecordLinkFieldElement` | `RecordLinkField` — allow_existing_records, linked_form_id, etc. |
+| `FormAttachmentFieldElement` | `AttachmentField` |
+| `FormCheckboxFieldElement` | `CheckboxField` |
+| `FormDynamicFieldElement` | `DynamicField` |
+| `FormLocationFieldElement` | `LocationField` |
+| `FormButtonFieldElement` | `ButtonField` |
+| `FormSketchFieldElement` | `SketchField` — min_length, max_length |
+| `FormLabelElement` | `Label` |
+| `FormSectionElement` | `Section` — display, nested elements |
+| `FormRepeatableElement` | `Repeatable` — nested elements, title_field_keys, geometry_types |
+| `FormStatusField` | Status field — choices (with color), default_value, enabled, read_only |
+| `FormBody` | `fulcrum-core/src/form.js` — top-level form attributes |
+| `FormRequest` | Wrapper `{ "form": FormBody }` |
+| `FormElementCondition` | Visibility/required condition rule |
+| `FormElementChoice` | Choice option (label, value, color) |
+| `FormClassificationItem` | Hierarchical classification item (recursive) |
+| `FormYesNoOption` | Yes/No option shape |
+| `FormCalculatedDisplay` | Calculated field display style |


+GET https://raw.githubusercontent.com/fulcrumapp/fulcrum-core/main/src/form.js
+```
+
+Use `fetch_webpage` or `mcp_github_github_get_file_contents` to retrieve these.


feat: add workflow to validate OpenAPI schemas in reference/rest-api.…

b9a4974

…json

treyhyde changed the base branch from main to v2 May 8, 2026 17:49

treyhyde requested review from a team as code owners May 8, 2026 17:49

fix: improve grep command for checking external schema references in …

766e8aa

…OpenAPI validation

Copilot AI review requested due to automatic review settings May 8, 2026 19:06

Copilot started reviewing on behalf of treyhyde May 8, 2026 19:07 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread .github/skills/sync-form-schema/SKILL.md Outdated

Comment thread .github/skills/sync-form-schema/SKILL.md Outdated

fix: ensure workflow triggers on changes to validate-openapi.yml

43ec293

pedrodotavila previously approved these changes May 8, 2026

View reviewed changes

pedrodotavila mentioned this pull request May 8, 2026

Add new form element schemas for enhanced functionality #63

Merged

osbornk reviewed May 8, 2026

View reviewed changes

Merge branch 'v2' into debt/readme-action

c3f156a

Copilot AI review requested due to automatic review settings June 5, 2026 23:00

Copilot started reviewing on behalf of treyhyde June 5, 2026 23:00 View session

Copilot AI reviewed Jun 5, 2026

View reviewed changes

Comment thread .github/workflows/validate-openapi.yml

Comment thread .github/workflows/validate-openapi.yml

Comment thread .github/skills/sync-form-schema/SKILL.md Outdated

Comment thread .github/skills/sync-form-schema/SKILL.md Outdated

Comment thread .github/skills/sync-form-schema/SKILL.md

Potential fix for pull request finding

061d593

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 16, 2026 15:17

Potential fix for pull request finding

07f0ae3

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started reviewing on behalf of treyhyde June 16, 2026 15:18 View session

treyhyde and others added 4 commits June 16, 2026 08:18

Potential fix for pull request finding

6bf6bf1

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

12bb007

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Merge branch 'v2' into debt/readme-action

7879606

Potential fix for pull request finding

f8439a7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Jun 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add workflow to validate OpenAPI schemas in reference/rest-api.json#64

feat: add workflow to validate OpenAPI schemas in reference/rest-api.json#64
treyhyde wants to merge 10 commits into
v2from
debt/readme-action

treyhyde commented May 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

pedrodotavila left a comment

Uh oh!

osbornk May 8, 2026

Uh oh!

treyhyde Jun 16, 2026

Uh oh!

osbornk May 8, 2026

Uh oh!

treyhyde Jun 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

treyhyde commented May 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

pedrodotavila left a comment

Choose a reason for hiding this comment

Uh oh!

osbornk May 8, 2026

Choose a reason for hiding this comment

Uh oh!

treyhyde Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

osbornk May 8, 2026

Choose a reason for hiding this comment

Uh oh!

treyhyde Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants