@friggframework/schemas 2.0.0--canary.701.3b01ea3.0 → 2.0.0--canary.705.f070722.0

package/README.md

@@ -95,6 +95,31 @@ const appSchema = getSchema('app-definition');
 console.log('App definition schema:', appSchema);
 ```
 
+## Schema Identifiers and Hosting
+
+Every schema's `$id` is its public URL:
+
+```
+https://friggframework.org/schemas/<name>/v<major>.<minor>.json
+```
+
+for example `https://friggframework.org/schemas/app-definition/v1.0.json`.
+friggframework.org serves each file at that URL (with
+`Content-Type: application/schema+json` and open CORS), so editors can fetch
+it from a `$schema` reference. The URL is a name, not a dependency: this
+package, `frigg validate` and the runtime resolve every `$id` from the
+installed files and never fetch it.
+
+- A version is immutable once a stable release ships it. A backward-compatible
+  change gets a new minor version, a breaking change a new major version.
+- `validate()` and `getSchema()` accept a schema name, its `$id`, or the
+  unversioned id it had before 2.0.1 (kept as an alias for one release).
+- The website copies live in `website/schemas/` and are committed. After you
+  change a schema, run `npm run sync:hosted` here and commit the result;
+  `tests/hosted-schemas.test.js` fails while a copy is missing or stale.
+
+The rules are in ADR-051, "Hosted schemas" amendment.
+
 ## Available Schemas
 
 ### App Definition Schema
@@ -172,9 +197,7 @@ Defines the structure for Frigg API modules.
 **Key Properties:**
 - `moduleName` (required): Module identifier
 - `getName` (required): Function returning module name
-- `requiredAuthMethods` (required): Authentication configuration (includes optional `getAuthorizationRequirements` and `setAuthParams` for API-key modules)
-- `modelName`: Entity/credential model name used by the Module runtime
-- Real Definitions (classes/functions) are accepted by `validateApiModuleDefinition` via a schema view.
+- `requiredAuthMethods` (required): Authentication configuration
 - `env`: Environment variable configuration
 - `config`: Module-specific configuration
 
@@ -355,7 +378,12 @@ Validates core data models (User, Entity, Credential).
 Returns all available schemas as an object.
 
 #### `getSchema(schemaName)`
-Returns a specific schema by name.
+Returns a specific schema by name (`app-definition`), by `$id`, or by its legacy unversioned id.
+
+#### `parseSchemaId(id)`
+Returns `{ name, version, hostedPath }` for an `$id` on the
+`https://friggframework.org/schemas/<name>/v<x.y>.json` pattern, or `null`.
+`SCHEMA_ID_PATTERN` and `LEGACY_SCHEMA_IDS` are exported too.
 
 ### Utility Functions
 

package/index.js

@@ -16,9 +16,7 @@ const {
     applyAppDefinitionDefaults,
     toAppDefinitionSchemaView,
 } = require('./app-definition');
-const {
-    toApiModuleDefinitionSchemaView,
-} = require('./api-module-definition');
+const schemaIds = require('./schema-ids');
 
 // Initialize AJV with formats
 const ajv = new Ajv({ 
@@ -52,7 +50,16 @@ schemaFiles.forEach(file => {
     const schemaName = file.replace('.schema.json', '');
     
     schemas[schemaName] = schemaContent;
-    ajv.addSchema(schemaContent, schemaName);
+    schemaIds.addSchemaWithAliases(ajv, schemaContent, schemaName);
+});
+
+// Schema name for each `$id` and legacy id, so getSchema() also accepts a URL.
+const schemaNamesById = {};
+Object.entries(schemas).forEach(([schemaName, schema]) => {
+    schemaNamesById[schema.$id] = schemaName;
+    (schemaIds.LEGACY_SCHEMA_IDS[schemaName] || []).forEach(legacyId => {
+        schemaNamesById[legacyId] = schemaName;
+    });
 });
 
 /**
@@ -102,18 +109,12 @@ function validateIntegrationDefinition(integrationDefinition) {
 }
 
 /**
- * Validate API Module Definition.
- * Real Definitions carry classes and functions; validate the serialisable
- * view and return the original definition (same pattern as validateAppDefinition).
- * @param {object} apiModuleDefinition - API module definition object to validate
+ * Validate API Module Definition
+ * @param {object} apiModuleDefinition - API module definition object to validate  
  * @returns {object} - Validation result
  */
 function validateApiModuleDefinition(apiModuleDefinition) {
-    const result = validate(
-        'api-module-definition',
-        toApiModuleDefinitionSchemaView(apiModuleDefinition)
-    );
-    return { ...result, data: apiModuleDefinition };
+    return validate('api-module-definition', apiModuleDefinition);
 }
 
 /**
@@ -341,15 +342,16 @@ function getSchemas() {
 }
 
 /**
- * Get a specific schema by name
- * @param {string} schemaName - Name of the schema to retrieve
+ * Get a specific schema by name or `$id`
+ * @param {string} schemaName - Schema name (`app-definition`), its `$id`, or a legacy unversioned id
  * @returns {object} - Schema object
  */
 function getSchema(schemaName) {
-    if (!schemas[schemaName]) {
+    const name = schemas[schemaName] ? schemaName : schemaNamesById[schemaName];
+    if (!name) {
         throw new Error(`Schema '${schemaName}' not found. Available schemas: ${Object.keys(schemas).join(', ')}`);
     }
-    return schemas[schemaName];
+    return schemas[name];
 }
 
 /**
@@ -378,7 +380,6 @@ module.exports = {
     validateAppDefinition,
     applyAppDefinitionDefaults,
     toAppDefinitionSchemaView,
-    toApiModuleDefinitionSchemaView,
     validateIntegrationDefinition,
     validateApiModuleDefinition,
     validateServerlessConfig,
@@ -411,6 +412,11 @@ module.exports = {
     schemas,
     ajv,
 
+    // Schema identifiers (https://friggframework.org/schemas/<name>/v<x.y>.json)
+    SCHEMA_ID_PATTERN: schemaIds.SCHEMA_ID_PATTERN,
+    LEGACY_SCHEMA_IDS: schemaIds.LEGACY_SCHEMA_IDS,
+    parseSchemaId: schemaIds.parseSchemaId,
+
     // Middleware exports
     middleware: schemaValidationMiddleware,
     validateBody: schemaValidationMiddleware.validateBody,

package/middleware/schema-validation.js

@@ -9,6 +9,7 @@ const Ajv = require('ajv');
 const addFormats = require('ajv-formats');
 const fs = require('fs');
 const path = require('path');
+const { addSchemaWithAliases } = require('../schema-ids');
 
 // Initialize AJV with formats
 const ajv = new Ajv({
@@ -33,7 +34,7 @@ schemaFiles.forEach(file => {
     if (fs.existsSync(schemaPath)) {
         const schemaContent = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
         const schemaName = file.replace('.schema.json', '');
-        ajv.addSchema(schemaContent, schemaName);
+        addSchemaWithAliases(ajv, schemaContent, schemaName);
     }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friggframework/schemas",
-  "version": "2.0.0--canary.701.3b01ea3.0",
+  "version": "2.0.0--canary.705.f070722.0",
   "description": "Canonical JSON Schema definitions for Frigg Framework",
   "main": "index.js",
   "author": "",
@@ -19,7 +19,9 @@
   "scripts": {
     "test": "jest",
     "validate": "node scripts/validate-schemas.js",
-    "build": "node scripts/build-schemas.js"
+    "build": "node scripts/build-schemas.js",
+    "sync:hosted": "node scripts/sync-hosted-schemas.js",
+    "check:hosted": "node scripts/sync-hosted-schemas.js --check"
   },
   "keywords": [
     "frigg",
@@ -40,8 +42,8 @@
     "mocks/",
     "middleware/",
     "app-definition.js",
-    "api-module-definition.js",
+    "schema-ids.js",
     "index.js"
   ],
-  "gitHead": "3b01ea3abd65f1771e9bb1f143168da6acff4125"
+  "gitHead": "f070722ad939d3221446e24653352373a5f4e0f6"
 }

package/schema-ids.js

@@ -0,0 +1,69 @@
+/**
+ * Schema identifiers (ADR-051, "Hosted schemas" amendment).
+ *
+ * Every Frigg JSON Schema has the `$id`
+ *   https://friggframework.org/schemas/<name>/v<major>.<minor>.json
+ * and friggframework.org serves the file at exactly that URL. The `$id` is a
+ * name, not a location the runtime reads: validation always resolves it from
+ * this package and never fetches it.
+ */
+
+const SCHEMA_BASE_URL = 'https://friggframework.org/';
+
+const SCHEMA_ID_PATTERN =
+    /^https:\/\/friggframework\.org\/schemas\/([a-z0-9]+(?:-[a-z0-9]+)*)\/v(0|[1-9]\d*)\.(0|[1-9]\d*)\.json$/;
+
+/**
+ * Unversioned ids the schemas carried before 2.0.1. They never resolved over
+ * HTTP, but code may pass them to `validate()`/`getSchema()` or Ajv, so the
+ * package still registers them as aliases of the current schema.
+ *
+ * @deprecated Remove in the release after 2.0.1.
+ */
+const LEGACY_SCHEMA_IDS = Object.freeze({
+    'api-authorization': ['https://friggframework.org/schemas/api-authorization.json'],
+    'api-credentials': ['https://friggframework.org/schemas/api-credentials.json'],
+    'api-entities': ['https://friggframework.org/schemas/api-entities.json'],
+    'api-proxy': ['https://friggframework.org/schemas/api-proxy.json'],
+    'api-module-definition': ['https://schemas.friggframework.org/api-module-definition.schema.json'],
+    'app-definition': ['https://schemas.friggframework.org/app-definition.schema.json'],
+    'core-models': ['https://schemas.friggframework.org/core-models.schema.json'],
+    'environment-config': ['https://schemas.friggframework.org/environment-config.schema.json'],
+    'integration-definition': ['https://schemas.friggframework.org/integration-definition.schema.json'],
+    'serverless-config': ['https://schemas.friggframework.org/serverless-config.schema.json'],
+});
+
+/**
+ * Parse a schema `$id`.
+ * @param {string} id
+ * @returns {{ name: string, version: string, hostedPath: string } | null}
+ *   `hostedPath` is the path under the website root (`schemas/<name>/v1.0.json`).
+ */
+function parseSchemaId(id) {
+    const match = typeof id === 'string' ? SCHEMA_ID_PATTERN.exec(id) : null;
+    if (!match) return null;
+    const [, name, major, minor] = match;
+    const version = `${major}.${minor}`;
+    return { name, version, hostedPath: `schemas/${name}/v${version}.json` };
+}
+
+/**
+ * Register a schema with Ajv under its file name, its `$id`, and its legacy ids.
+ * @param {import('ajv').default} ajv
+ * @param {object} schema - parsed schema (its `$id` registers automatically)
+ * @param {string} name - file name without `.schema.json`
+ */
+function addSchemaWithAliases(ajv, schema, name) {
+    ajv.addSchema(schema, name);
+    for (const legacyId of LEGACY_SCHEMA_IDS[name] || []) {
+        ajv.addSchema({ ...schema, $id: legacyId });
+    }
+}
+
+module.exports = {
+    SCHEMA_BASE_URL,
+    SCHEMA_ID_PATTERN,
+    LEGACY_SCHEMA_IDS,
+    parseSchemaId,
+    addSchemaWithAliases,
+};

package/schemas/api-authorization.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://friggframework.org/schemas/api-authorization.json",
+  "$id": "https://friggframework.org/schemas/api-authorization/v1.0.json",
   "title": "Frigg Authorization API Schemas",
   "description": "JSON schemas for authorization and authentication API requests and responses",
   "definitions": {

package/schemas/api-credentials.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://friggframework.org/schemas/api-credentials.json",
+  "$id": "https://friggframework.org/schemas/api-credentials/v1.0.json",
   "title": "Frigg Credentials API Schemas",
   "description": "JSON schemas for credentials API requests and responses",
   "definitions": {

package/schemas/api-entities.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://friggframework.org/schemas/api-entities.json",
+  "$id": "https://friggframework.org/schemas/api-entities/v1.0.json",
   "title": "Frigg Entities API Schemas",
   "description": "JSON schemas for entities API requests and responses",
   "definitions": {

package/schemas/api-module-definition.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.friggframework.org/api-module-definition.schema.json",
+  "$id": "https://friggframework.org/schemas/api-module-definition/v1.0.json",
   "title": "Frigg API Module Definition",
   "description": "Schema for defining a Frigg API module including authentication, API configuration, and required methods.",
   "type": "object",
@@ -27,13 +27,6 @@
       "minLength": 1,
       "maxLength": 100
     },
-    "modelName": {
-      "type": "string",
-      "description": "Entity/credential model name used by the Module runtime (e.g. 'Fathom'). Distinct from moduleName, which is the package identifier.",
-      "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
-      "minLength": 1,
-      "maxLength": 100
-    },
     "requiredAuthMethods": {
       "type": "object",
       "description": "Required authentication methods and configuration",
@@ -97,22 +90,6 @@
             "type": {"type": "string", "enum": ["function"]},
             "async": {"type": "boolean", "default": true}
           }
-        },
-        "getAuthorizationRequirements": {
-          "type": "object",
-          "description": "Method that returns the authorization requirements (type, jsonSchema/uiSchema) for non-OAuth flows such as API key",
-          "properties": {
-            "type": {"type": "string", "enum": ["function"]},
-            "async": {"type": "boolean", "default": true}
-          }
-        },
-        "setAuthParams": {
-          "type": "object",
-          "description": "Method that applies authorization parameters (e.g. API key) to the API instance",
-          "properties": {
-            "type": {"type": "string", "enum": ["function"]},
-            "async": {"type": "boolean", "default": true}
-          }
         }
       },
       "additionalProperties": false

package/schemas/api-proxy.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://friggframework.org/schemas/api-proxy.json",
+  "$id": "https://friggframework.org/schemas/api-proxy/v1.0.json",
   "title": "Frigg Proxy API Schemas",
   "description": "JSON schemas for proxy API requests and responses that forward calls to external APIs",
   "definitions": {

package/schemas/app-definition.schema.json

@@ -1,6 +1,6 @@
 {
   "$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",
   "title": "Frigg Application Definition",
   "description": "Schema for defining a Frigg application configuration including integrations, infrastructure, security settings, and deployment options.",
   "type": "object",

package/schemas/core-models.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.friggframework.org/core-models.schema.json",
+  "$id": "https://friggframework.org/schemas/core-models/v1.0.json",
   "title": "Frigg Core Data Models",
   "description": "Schema definitions for core Frigg data models including User, Entity, and Credential.",
   "definitions": {

package/schemas/environment-config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.friggframework.org/environment-config.schema.json",
+  "$id": "https://friggframework.org/schemas/environment-config/v1.0.json",
   "title": "Frigg Environment Configuration",
   "description": "Schema for environment variable configuration and validation in Frigg applications.",
   "type": "object",

package/schemas/integration-definition.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.friggframework.org/integration-definition.schema.json",
+  "$id": "https://friggframework.org/schemas/integration-definition/v1.0.json",
   "title": "Frigg Integration Definition",
   "description": "Schema for defining a Frigg integration including configuration, options, and display properties.",
   "type": "object",

package/schemas/serverless-config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://schemas.friggframework.org/serverless-config.schema.json",
+  "$id": "https://friggframework.org/schemas/serverless-config/v1.0.json",
   "title": "Frigg Serverless Configuration",
   "description": "Schema for Serverless Framework configuration used in Frigg applications for AWS deployment.",
   "type": "object",

package/api-module-definition.js

@@ -1,93 +0,0 @@
-/**
- * API module definition helpers shared by validators and the frigg CLI.
- * Real Definitions carry classes and functions that JSON Schema cannot
- * describe; validators check the serialisable view produced here.
- */
-
-function isPlainObject(value) {
-    if (value === null || typeof value !== 'object') return false;
-    const proto = Object.getPrototypeOf(value);
-    return proto === Object.prototype || proto === null;
-}
-
-/**
- * Schema descriptor for a JavaScript function (see api-module-definition
- * schema: `{ type: "function", async?: boolean }`).
- *
- * @param {Function} fn
- * @returns {{ type: 'function', async?: boolean }}
- */
-function toFunctionDescriptor(fn) {
-    const descriptor = { type: 'function' };
-    if (fn && fn.constructor && fn.constructor.name === 'AsyncFunction') {
-        descriptor.async = true;
-    }
-    return descriptor;
-}
-
-/**
- * JSON Schema cannot describe a JavaScript class or function. Validators
- * therefore check this serialisable view: the API class becomes an empty
- * object, functions become `{ type: "function" }` descriptors, and
- * `undefined` env values are dropped (unset `process.env.*` entries).
- *
- * @param {object} definition the `Definition` exported by an API module
- * @returns {object} a view suitable for the api-module-definition schema
- */
-function toApiModuleDefinitionSchemaView(definition) {
-    if (!isPlainObject(definition)) return definition;
-
-    const view = { ...definition };
-
-    if (typeof view.API === 'function') {
-        view.API = {};
-    }
-
-    if (typeof view.getName === 'function') {
-        view.getName = toFunctionDescriptor(view.getName);
-    }
-
-    if (isPlainObject(view.requiredAuthMethods)) {
-        const methods = { ...view.requiredAuthMethods };
-        for (const [key, value] of Object.entries(methods)) {
-            if (typeof value === 'function') {
-                methods[key] = toFunctionDescriptor(value);
-            }
-        }
-        view.requiredAuthMethods = methods;
-    }
-
-    if (isPlainObject(view.env)) {
-        const env = {};
-        for (const [key, value] of Object.entries(view.env)) {
-            if (value !== undefined) env[key] = value;
-        }
-        view.env = env;
-    }
-
-    if (isPlainObject(view.manager)) {
-        const manager = { ...view.manager };
-        for (const key of ['Entity', 'Credential']) {
-            if (typeof manager[key] === 'function') {
-                manager[key] = {};
-            }
-        }
-        if (isPlainObject(manager.methods)) {
-            const methods = { ...manager.methods };
-            for (const [key, value] of Object.entries(methods)) {
-                if (typeof value === 'function') {
-                    methods[key] = {};
-                }
-            }
-            manager.methods = methods;
-        }
-        view.manager = manager;
-    }
-
-    return view;
-}
-
-module.exports = {
-    toApiModuleDefinitionSchemaView,
-    toFunctionDescriptor,
-};