Repository navigation
feat(schemas): versioned schema ids, hosted on friggframework.org - #705
seanspeaks wants to merge 2 commits into
Conversation
seanspeaks
added
release
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.
Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.
✅ Deploy Preview for friggframework-org ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Frigg 2.0.1 review (Group 2) — COMMENT onlyChecklist
Verdict (would): changes needed Findings
Implementation of ids, aliases, offline resolve, and headers looks correct. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| { | ||
| "$schema": "http://json-schema.org/draft-07/schema#", | ||
| "$id": "https://schemas.friggframework.org/app-definition.schema.json", | ||
| "$id": "https://friggframework.org/schemas/app-definition/v1.0.json", |
There was a problem hiding this comment.
blocking (merge order with #666): this renames $id to …/app-definition/v1.0.json but the document body is still the pre-#666 schema. ADR-051’s hosted-schemas amendment makes v1.0 immutable once published.
Scenario: Ship this before #666 → public v1.0 rejects postgres.management: 'external' and fieldLevelEncryptionMethod: 'none', then #666 cannot safely overwrite the same URL. Sync hosted copies from the post-#666 schema (with those enums) before freezing v1.0.
Every schema in @friggframework/schemas now has the $id https://friggframework.org/schemas/<name>/v1.0.json (ADR-051, "Hosted schemas" amendment), replacing the two unversioned styles (friggframework.org/schemas/<name>.json and schemas.friggframework.org/<name>.schema.json), neither of which resolved. - The old ids stay registered as Ajv aliases for one release, in the package and in the middleware; getSchema() accepts a name, an $id or a legacy id. - scripts/sync-hosted-schemas.js copies each schema to website/schemas/<name>/v<x.y>.json, the path its $id names; the copies are committed so old versions keep resolving and a schema change is a website change. website/_headers serves them as application/schema+json with open CORS. - tests/hosted-schemas.test.js checks the id pattern, that every website copy matches its source and sits at its $id's path, and that every id and alias resolves from the package with http, https and fetch stubbed to throw. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
9cfd819 to
f070722
Compare
|
Summary
Gives every Frigg JSON Schema one identifier pattern and publishes the files at that URL, following the "Hosted schemas" amendment to ADR-051 (on #666, commit 923c975).
https://friggframework.org/schemas/<name>/v<major>.<minor>.json. The$idis exactly that URL.@friggframework/schemasused two unversioned styles,friggframework.org/schemas/<name>.jsonfor theapi-*schemas andschemas.friggframework.org/<name>.schema.jsonfor the other six. Neither resolved. They're now.../schemas/<name>/v1.0.json. They start at 1.0 rather than 0.x because they've shipped in every 2.0 prerelease andapp-definitionis enforced byfrigg validate/build/deploy, so they're supported contracts. v1.0 is frozen when 2.0.1 ships.index.jsand in the middleware (schema-ids.js).getSchema()now accepts a name, an$id, or a legacy id. No code in the monorepo looked a schema up by URL: lookups are by file name and are unchanged. There are no cross-schema$refs.scripts/sync-hosted-schemas.js(npm run sync:hostedin packages/schemas) copies each schema towebsite/schemas/<name>/v<x.y>.json, choosing the path from its$id. The copies are committed, not generated during the Netlify build:website/, so the site builds whenwebsite/changes. With committed copies, a schema change is a website change, and there's no build command or ignore rule to maintain.website/schemas/after its schema moves on, so a published URL keeps resolving. A build-time copy of the current files would drop it.website/_headersserves/schemas/*asapplication/schema+jsonwithAccess-Control-Allow-Origin: *.packages/core/integrations/definitions/schema/when that directory exists, so the ADR-063 schemas (capability-manifest/v0.1, which the API module manifests already reference) get published as soon as they land on next. Until they're synced, the test fails. This PR doesn't change those files.Validation stays offline
The runtime,
frigg validateand the CLI resolve every$idfrom the installed package. Nothing configures AjvloadSchema. A test loads the package withhttp,httpsandfetchstubbed to throw, then resolves every$idand every alias.Test plan
packages/schemas:npx jestpasses, 7 suites / 155 tests (baseline on next: 6 suites / 127 tests)npm run validate(packages/schemas): 10 schemas validnpm run check:hosted: 10 hosted schemas in syncNew
tests/hosted-schemas.test.jschecks four things:$idmatches the pattern and the file namewebsite/schemas/sits at the path its$idnames_headerscovers/schemas/*, and ids and aliases resolve with no network accessI also checked that it fails when a copy is edited and when the aliases are removed.
After merge:
curl -I https://friggframework.org/schemas/app-definition/v1.0.jsonreturns 200 withapplication/schema+jsonNotes
app-definition.schema.json. Whichever PR merges second takes the other's$idline and rerunsnpm run sync:hosted.integration-definition/v0.1for the declarative document, while this package'sintegration-definition(now v1.0) is the classDefinitionschema. The amendment gives the declarative document the name ADR-063 already plans:integration-document.🤖 Generated with Claude Code
https://claude.ai/code/session_013b2UUFaQ5Lk6TFPqzRr1j7
Note
Medium Risk
Changes public schema
$idURLs (mitigated by temporary legacy aliases); validation behavior should stay equivalent if callers used file names, but external$schemareferences must adopt the new URLs.Overview
Introduces versioned, publicly hosted JSON Schema identifiers (ADR-051): every package schema’s
$idis nowhttps://friggframework.org/schemas/<name>/v1.0.json, replacing the previous unversionedfriggframework.organdschemas.friggframework.orgURLs.Runtime and tooling gain
schema-ids.jswithparseSchemaId, legacy-id aliases (one release), andaddSchemaWithAliasesso Ajv,getSchema(), andvalidate()accept schema names, new$ids, or old ids without HTTP fetches. The Express middleware registers the same aliases.Publishing adds
npm run sync:hosted/check:hostedto copy schemas into committedwebsite/schemas/paths derived from$id, plus Netlifywebsite/_headersforapplication/schema+jsonand open CORS on/schemas/*.hosted-schemas.test.jsenforces id shape, byte-identical website copies, offline resolution, and header coverage.Reviewed by Cursor Bugbot for commit f070722. Bugbot is set up for automated code reviews on this repo. Configure here.
📦 Published PR as canary version:
2.0.0--canary.705.f070722.0✨ Test out this PR locally via:
npm install @friggframework/admin-scripts@2.0.0--canary.705.f070722.0 npm install @friggframework/core@2.0.0--canary.705.f070722.0 npm install @friggframework/devtools@2.0.0--canary.705.f070722.0 npm install @friggframework/eslint-config@2.0.0--canary.705.f070722.0 npm install @friggframework/prettier-config@2.0.0--canary.705.f070722.0 npm install @friggframework/schemas@2.0.0--canary.705.f070722.0 npm install @friggframework/serverless-plugin@2.0.0--canary.705.f070722.0 npm install @friggframework/test@2.0.0--canary.705.f070722.0 npm install @friggframework/ui@2.0.0--canary.705.f070722.0 # or yarn add @friggframework/admin-scripts@2.0.0--canary.705.f070722.0 yarn add @friggframework/core@2.0.0--canary.705.f070722.0 yarn add @friggframework/devtools@2.0.0--canary.705.f070722.0 yarn add @friggframework/eslint-config@2.0.0--canary.705.f070722.0 yarn add @friggframework/prettier-config@2.0.0--canary.705.f070722.0 yarn add @friggframework/schemas@2.0.0--canary.705.f070722.0 yarn add @friggframework/serverless-plugin@2.0.0--canary.705.f070722.0 yarn add @friggframework/test@2.0.0--canary.705.f070722.0 yarn add @friggframework/ui@2.0.0--canary.705.f070722.0