@afps-spec/schema 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afps-spec/schema",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "files": [
     "src",
@@ -11,12 +11,17 @@
     "./v1/*": "./v1/*"
   },
   "scripts": {
-    "generate": "bun src/generate.ts"
+    "generate": "bun src/generate.ts",
+    "check": "bun src/generate.ts --check",
+    "test": "bun test",
+    "test:conformance": "bun test tests/conformance.test.ts"
   },
   "dependencies": {
+    "semver": "^7.7.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/semver": "^7.7.1",
     "bun-types": "latest"
   }
 }

package/src/generate.ts

@@ -3,12 +3,14 @@
  *
  * Change MAJOR to generate schemas for a different spec version.
  *
- * Usage: bun src/generate.ts  (from schema/)
+ * Usage:
+ *   bun src/generate.ts          Generate/update JSON schemas
+ *   bun src/generate.ts --check  Verify committed schemas match Zod source (CI)
  */
 
 import { toJSONSchema } from "zod/v4/core";
 import { resolve, dirname } from "node:path";
-import { writeFile, mkdir } from "node:fs/promises";
+import { writeFile, mkdir, readFile } from "node:fs/promises";
 import { createSchemas } from "./schemas.ts";
 
 const MAJOR = 1;
@@ -16,6 +18,8 @@ const VERSION_TAG = `v${MAJOR}`;
 const BASE_URL = "https://afps.appstrate.dev/schema";
 const OUTPUT_DIR = resolve(dirname(import.meta.filename!), "..", VERSION_TAG);
 
+const isCheck = process.argv.includes("--check");
+
 const { flowManifestSchema, skillManifestSchema, toolManifestSchema, providerManifestSchema } =
   createSchemas(MAJOR);
 
@@ -54,7 +58,11 @@ const entries = [
   },
 ];
 
-await mkdir(OUTPUT_DIR, { recursive: true });
+if (!isCheck) {
+  await mkdir(OUTPUT_DIR, { recursive: true });
+}
+
+let mismatch = false;
 
 for (const entry of entries) {
   const jsonSchema = toJSONSchema(entry.schema, {
@@ -72,9 +80,36 @@ for (const entry of entries) {
     ...jsonSchema,
   };
 
+  const generated = JSON.stringify(final, null, 2) + "\n";
   const filePath = resolve(OUTPUT_DIR, entry.filename);
-  await writeFile(filePath, JSON.stringify(final, null, 2) + "\n");
-  console.log(`  ✓ ${VERSION_TAG}/${entry.filename}`);
+
+  if (isCheck) {
+    let committed: string;
+    try {
+      committed = await readFile(filePath, "utf-8");
+    } catch {
+      console.error(`  ✗ ${VERSION_TAG}/${entry.filename} — file missing`);
+      mismatch = true;
+      continue;
+    }
+    if (committed !== generated) {
+      console.error(`  ✗ ${VERSION_TAG}/${entry.filename} — out of date`);
+      mismatch = true;
+    } else {
+      console.log(`  ✓ ${VERSION_TAG}/${entry.filename}`);
+    }
+  } else {
+    await writeFile(filePath, generated);
+    console.log(`  ✓ ${VERSION_TAG}/${entry.filename}`);
+  }
 }
 
-console.log(`\nGenerated ${entries.length} schemas in ${OUTPUT_DIR}`);
+if (isCheck) {
+  if (mismatch) {
+    console.error("\nJSON schemas are out of date. Run `bun run generate` to update.");
+    process.exit(1);
+  }
+  console.log("\nAll JSON schemas are up to date.");
+} else {
+  console.log(`\nGenerated ${entries.length} schemas in ${OUTPUT_DIR}`);
+}

package/src/index.ts

@@ -11,4 +11,14 @@ export {
   skillManifestSchema,
   toolManifestSchema,
   providerManifestSchema,
+  // Shared sub-schemas — reusable by consumers
+  authModeEnum,
+  providerDefinition,
+  oauth2Config,
+  oauth1Config,
+  credentialsConfig,
+  providerConfiguration,
+  setupGuide,
+  schemaProperty,
+  schemaObject,
 } from "./schemas.ts";

package/src/schemas.ts

@@ -11,6 +11,7 @@
  */
 
 import { z } from "zod";
+import semver from "semver";
 
 // ─────────────────────────────────────────────
 // Shared patterns and primitives
@@ -19,8 +20,17 @@ import { z } from "zod";
 const SLUG_PATTERN = "[a-z0-9]([a-z0-9-]*[a-z0-9])?";
 const SCOPED_NAME_REGEX = new RegExp(`^@${SLUG_PATTERN}\\/${SLUG_PATTERN}$`);
 
-const scopedName = z.string().regex(SCOPED_NAME_REGEX);
-const semverRange = z.string().min(1);
+const scopedName = z.string().regex(SCOPED_NAME_REGEX, {
+  error: "Must follow @scope/name format",
+});
+
+const semverVersion = z.string().refine((v) => semver.valid(v) !== null, {
+  error: "Must be a valid semver version (e.g. 1.0.0)",
+});
+
+const semverRange = z.string().refine((v) => semver.validRange(v) !== null, {
+  error: "Must be a valid semver range (e.g. ^1.0.0, ~2.1, >=3.0.0)",
+});
 
 // ─────────────────────────────────────────────
 // Schema system (§5)
@@ -28,7 +38,7 @@ const semverRange = z.string().min(1);
 
 const fieldTypeEnum = z.enum(["string", "number", "boolean", "array", "object", "file"]);
 
-const schemaProperty = z.looseObject({
+export const schemaProperty = z.looseObject({
   type: fieldTypeEnum,
   description: z.string().optional(),
   default: z.unknown().optional(),
@@ -38,10 +48,10 @@ const schemaProperty = z.looseObject({
   accept: z.string().optional(),
   maxSize: z.number().positive().optional(),
   multiple: z.boolean().optional(),
-  maxFiles: z.number().positive().optional(),
+  maxFiles: z.number().int().positive().optional(),
 });
 
-const schemaObject = z.looseObject({
+export const schemaObject = z.looseObject({
   type: z.literal("object"),
   properties: z.record(z.string(), schemaProperty),
   required: z.array(z.string()).optional(),
@@ -68,7 +78,7 @@ const dependenciesSchema = z
 // Provider configuration (§4.4)
 // ─────────────────────────────────────────────
 
-const providerConfiguration = z.looseObject({
+export const providerConfiguration = z.looseObject({
   scopes: z.array(z.string()).optional(),
   connectionMode: z.enum(["user", "admin"]).optional(),
 });
@@ -87,31 +97,36 @@ const toolInterface = z.object({
 // Auth and provider internals (§3.5 + §7)
 // ─────────────────────────────────────────────
 
-const authModeEnum = z.enum(["oauth2", "oauth1", "api_key", "basic", "custom"]);
+export const authModeEnum = z.enum(["oauth2", "oauth1", "api_key", "basic", "custom"]);
+
+/** OAuth2 configuration sub-object. Required fields per §7.2; extensible for implementation-specific fields. */
+export const oauth2Config = z.looseObject({
+  authorizationUrl: z.string(),
+  tokenUrl: z.string(),
+});
 
-const providerDefinition = z.looseObject({
+/** OAuth1 configuration sub-object. Required fields per §7.3; extensible for implementation-specific fields. */
+export const oauth1Config = z.looseObject({
+  requestTokenUrl: z.string(),
+  accessTokenUrl: z.string(),
+});
+
+/** Credential configuration sub-object. Required fields per §7.4; extensible for implementation-specific fields. */
+export const credentialsConfig = z.looseObject({
+  schema: z.record(z.string(), z.unknown()),
+});
+
+export const providerDefinition = z.looseObject({
   authMode: authModeEnum,
-  authorizationUrl: z.string().optional(),
-  tokenUrl: z.string().optional(),
-  refreshUrl: z.string().optional(),
-  defaultScopes: z.array(z.string()).optional(),
-  scopeSeparator: z.string().optional(),
-  pkceEnabled: z.boolean().optional(),
-  tokenAuthMethod: z.string().optional(),
-  authorizationParams: z.record(z.string(), z.unknown()).optional(),
-  tokenParams: z.record(z.string(), z.unknown()).optional(),
-  requestTokenUrl: z.string().optional(),
-  accessTokenUrl: z.string().optional(),
-  credentialSchema: z.record(z.string(), z.unknown()).optional(),
-  credentialFieldName: z.string().optional(),
-  credentialHeaderName: z.string().optional(),
-  credentialHeaderPrefix: z.string().optional(),
+  oauth2: oauth2Config.optional(),
+  oauth1: oauth1Config.optional(),
+  credentials: credentialsConfig.optional(),
   authorizedUris: z.array(z.string()).optional(),
   allowAllUris: z.boolean().optional(),
   availableScopes: z.array(z.unknown()).optional(),
 });
 
-const setupGuide = z
+export const setupGuide = z
   .object({
     callbackUrlHint: z.string().optional(),
     steps: z
@@ -132,11 +147,13 @@ const setupGuide = z
 export function createSchemas(majorVersion: number) {
   const schemaVersionField = z
     .string()
-    .regex(new RegExp(`^${majorVersion}\\.(0|[1-9]\\d*)$`));
+    .regex(new RegExp(`^${majorVersion}\\.(0|[1-9]\\d*)$`), {
+      error: `Must follow MAJOR.MINOR format (e.g. "${majorVersion}.0")`,
+    });
 
   const commonFields = {
     name: scopedName,
-    version: z.string().min(1),
+    version: semverVersion,
     type: z.enum(["flow", "skill", "tool", "provider"]),
     displayName: z.string().optional(),
     description: z.string().optional(),
@@ -152,7 +169,7 @@ export function createSchemas(majorVersion: number) {
     type: z.literal("flow"),
     schemaVersion: schemaVersionField,
     displayName: z.string().min(1),
-    author: z.string(),
+    author: z.string().min(1),
     providersConfiguration: z.record(scopedName, providerConfiguration).optional(),
     input: schemaWrapper.optional(),
     output: schemaWrapper.optional(),
@@ -172,15 +189,80 @@ export function createSchemas(majorVersion: number) {
     tool: toolInterface,
   });
 
-  const providerManifestSchema = z.looseObject({
-    ...commonFields,
-    type: z.literal("provider"),
-    iconUrl: z.string().optional(),
-    categories: z.array(z.string()).optional(),
-    docsUrl: z.string().optional(),
-    definition: providerDefinition,
-    setupGuide: setupGuide,
-  });
+  const providerManifestSchema = z
+    .looseObject({
+      ...commonFields,
+      type: z.literal("provider"),
+      iconUrl: z.string().optional(),
+      categories: z.array(z.string()).optional(),
+      docsUrl: z.string().optional(),
+      definition: providerDefinition,
+      setupGuide: setupGuide,
+    })
+    .superRefine((val, ctx) => {
+      const mode = val.definition?.authMode;
+      if (mode === "oauth2") {
+        if (!val.definition.oauth2) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["definition", "oauth2"],
+            message: "oauth2 configuration object is required for oauth2 authMode",
+          });
+        } else {
+          if (!val.definition.oauth2.authorizationUrl) {
+            ctx.addIssue({
+              code: "custom",
+              path: ["definition", "oauth2", "authorizationUrl"],
+              message: "Required for oauth2 authMode",
+            });
+          }
+          if (!val.definition.oauth2.tokenUrl) {
+            ctx.addIssue({
+              code: "custom",
+              path: ["definition", "oauth2", "tokenUrl"],
+              message: "Required for oauth2 authMode",
+            });
+          }
+        }
+      } else if (mode === "oauth1") {
+        if (!val.definition.oauth1) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["definition", "oauth1"],
+            message: "oauth1 configuration object is required for oauth1 authMode",
+          });
+        } else {
+          if (!val.definition.oauth1.requestTokenUrl) {
+            ctx.addIssue({
+              code: "custom",
+              path: ["definition", "oauth1", "requestTokenUrl"],
+              message: "Required for oauth1 authMode",
+            });
+          }
+          if (!val.definition.oauth1.accessTokenUrl) {
+            ctx.addIssue({
+              code: "custom",
+              path: ["definition", "oauth1", "accessTokenUrl"],
+              message: "Required for oauth1 authMode",
+            });
+          }
+        }
+      } else if (mode === "api_key" || mode === "basic" || mode === "custom") {
+        if (!val.definition.credentials) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["definition", "credentials"],
+            message: `credentials configuration object is required for ${mode} authMode`,
+          });
+        } else if (!val.definition.credentials.schema) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["definition", "credentials", "schema"],
+            message: `credentials.schema is required for ${mode} authMode`,
+          });
+        }
+      }
+    });
 
   return { flowManifestSchema, skillManifestSchema, toolManifestSchema, providerManifestSchema };
 }

package/v1/flow.schema.json

@@ -10,8 +10,7 @@
       "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
     },
     "version": {
-      "type": "string",
-      "minLength": 1
+      "type": "string"
     },
     "type": {
       "type": "string",
@@ -50,8 +49,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "tools": {
@@ -61,8 +59,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "providers": {
@@ -72,15 +69,15 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         }
       },
       "additionalProperties": {}
     },
     "author": {
-      "type": "string"
+      "type": "string",
+      "minLength": 1
     },
     "providersConfiguration": {
       "type": "object",
@@ -162,8 +159,9 @@
                     "type": "boolean"
                   },
                   "maxFiles": {
-                    "type": "number",
-                    "exclusiveMinimum": 0
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
                   }
                 },
                 "required": [
@@ -251,8 +249,9 @@
                     "type": "boolean"
                   },
                   "maxFiles": {
-                    "type": "number",
-                    "exclusiveMinimum": 0
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
                   }
                 },
                 "required": [
@@ -340,8 +339,9 @@
                     "type": "boolean"
                   },
                   "maxFiles": {
-                    "type": "number",
-                    "exclusiveMinimum": 0
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
                   }
                 },
                 "required": [

package/v1/provider.schema.json

@@ -10,8 +10,7 @@
       "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
     },
     "version": {
-      "type": "string",
-      "minLength": 1
+      "type": "string"
     },
     "type": {
       "type": "string",
@@ -49,8 +48,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "tools": {
@@ -60,8 +58,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "providers": {
@@ -71,8 +68,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         }
       },
@@ -103,66 +99,54 @@
             "custom"
           ]
         },
-        "authorizationUrl": {
-          "type": "string"
-        },
-        "tokenUrl": {
-          "type": "string"
-        },
-        "refreshUrl": {
-          "type": "string"
-        },
-        "defaultScopes": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
-        "scopeSeparator": {
-          "type": "string"
-        },
-        "pkceEnabled": {
-          "type": "boolean"
-        },
-        "tokenAuthMethod": {
-          "type": "string"
-        },
-        "authorizationParams": {
+        "oauth2": {
           "type": "object",
-          "propertyNames": {
-            "type": "string"
+          "properties": {
+            "authorizationUrl": {
+              "type": "string"
+            },
+            "tokenUrl": {
+              "type": "string"
+            }
           },
+          "required": [
+            "authorizationUrl",
+            "tokenUrl"
+          ],
           "additionalProperties": {}
         },
-        "tokenParams": {
+        "oauth1": {
           "type": "object",
-          "propertyNames": {
-            "type": "string"
+          "properties": {
+            "requestTokenUrl": {
+              "type": "string"
+            },
+            "accessTokenUrl": {
+              "type": "string"
+            }
           },
+          "required": [
+            "requestTokenUrl",
+            "accessTokenUrl"
+          ],
           "additionalProperties": {}
         },
-        "requestTokenUrl": {
-          "type": "string"
-        },
-        "accessTokenUrl": {
-          "type": "string"
-        },
-        "credentialSchema": {
+        "credentials": {
           "type": "object",
-          "propertyNames": {
-            "type": "string"
+          "properties": {
+            "schema": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {}
+            }
           },
+          "required": [
+            "schema"
+          ],
           "additionalProperties": {}
         },
-        "credentialFieldName": {
-          "type": "string"
-        },
-        "credentialHeaderName": {
-          "type": "string"
-        },
-        "credentialHeaderPrefix": {
-          "type": "string"
-        },
         "authorizedUris": {
           "type": "array",
           "items": {

package/v1/skill.schema.json

@@ -10,8 +10,7 @@
       "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
     },
     "version": {
-      "type": "string",
-      "minLength": 1
+      "type": "string"
     },
     "type": {
       "type": "string",
@@ -49,8 +48,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "tools": {
@@ -60,8 +58,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "providers": {
@@ -71,8 +68,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         }
       },

package/v1/tool.schema.json

@@ -10,8 +10,7 @@
       "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
     },
     "version": {
-      "type": "string",
-      "minLength": 1
+      "type": "string"
     },
     "type": {
       "type": "string",
@@ -49,8 +48,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "tools": {
@@ -60,8 +58,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         },
         "providers": {
@@ -71,8 +68,7 @@
             "pattern": "^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
           },
           "additionalProperties": {
-            "type": "string",
-            "minLength": 1
+            "type": "string"
           }
         }
       },