mailschema 0.1.0 → 0.1.1

package/README.md

@@ -1,13 +1,15 @@
 # MailSchema
 
-JSON Schemas, TypeScript definitions and validation tools for the MailSchema Registry.
+JSON Schemas and validation tools for Mail Action Protocol 0.1 and the MailSchema Registry.
 
-Prepare a new interaction type, amend an existing definition, or declare an implementation's supported operations. This package checks the Registry contribution format. It does not implement email delivery, authorization or the draft Mail Action Protocol wire format.
+Validate MAP descriptions, requests, results and problems, or prepare a Registry contribution. The package is local and performs no network requests.
 
 ```sh
 npm install mailschema
 npx mailschema check contribution.json
 npx mailschema schema > contribution.schema.json
+npx mailschema check description.json --map
+npx mailschema check request.json --content-review
 ```
 
 Node.js 22 or newer. The JavaScript API is ESM; the CLI reads a local JSON file of at most 256 KiB and does not upload or modify it.
@@ -22,10 +24,18 @@ else assertContribution(candidate);
 const schema = getContributionSchema(); // Independent copy, JSON Schema Draft 2020-12.
 ```
 
+```js
+import { assertMapDocument, assertContentReviewRequest, getMapSchema } from 'mailschema';
+
+assertMapDocument(description);
+assertContentReviewRequest(request);
+const mapSchema = getMapSchema();
+```
+
 Use `assertTypeRecord(value)` or `mailschema check record.json --record` for expanded Registry records. `getRecordSchema()` returns the equivalent schema. The raw contribution schema is also exported as `mailschema/contribution.schema.json`.
 
 For a structurally valid contribution, `referenceErrors(contribution, catalog)` checks references against a supplied catalogue: current amendment bases, existing type names, exact implementation records, versions, profiles and operations. The catalogue contains `types` and `snapshots` arrays of `{ record, digest }` entries. It is never fetched automatically.
 
 `Contribution`, `TypeRecord`, `TypeDefinition`, `Implementation`, `Party` and `CatalogView` are exported TypeScript types. Successful validation does not verify a contributor's identity, establish product compatibility or accept a submission. Full repository review also checks competing amendments and contribution identifiers.
 
-Package version `0.1.0` is independent of any specification version. MIT licensed.
+Raw schemas are exported as `mailschema/map-0.1.schema.json`, `mailschema/content-review-0.1.schema.json` and `mailschema/contribution.schema.json`. Package version `0.2.0` is independent of the MAP profile version. MIT licensed.

package/{cli.mjs → bin/mailschema.js}

@@ -3,15 +3,19 @@ import { open } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import {
   assertContribution,
+  assertContentReviewRequest,
+  assertMapDocument,
   assertTypeRecord,
+  getContentReviewSchema,
   getContributionSchema,
+  getMapSchema,
   getRecordSchema,
-} from './dist/index.js';
+} from '../dist/index.js';
 
 const help = `MailSchema contribution tools
 
-  mailschema check <file.json> [--record]
-  mailschema schema [--record]
+  mailschema check <file.json> [--record | --map | --content-review]
+  mailschema schema [--record | --map | --content-review]
 
 Checks JSON structure and required fields locally. Registry references and
 editorial acceptance are separate checks. No files are uploaded or changed.`;
@@ -19,13 +23,37 @@ editorial acceptance are separate checks. No files are uploaded or changed.`;
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
-    options: { record: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+    options: {
+      record: { type: 'boolean' },
+      map: { type: 'boolean' },
+      'content-review': { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+    },
   });
   const [command, path, ...extra] = positionals;
+  const formats = [values.record, values.map, values['content-review']].filter(Boolean);
+  if (formats.length > 1) throw new Error('Choose only one document format.');
+  const selected = values['content-review']
+    ? 'Content Review request'
+    : values.map
+      ? 'MAP document'
+      : values.record
+        ? 'type record'
+        : 'contribution';
   if (values.help || !command) console.log(help);
   else if (command === 'schema' && !path && !extra.length)
     console.log(
-      JSON.stringify(values.record ? getRecordSchema() : getContributionSchema(), null, 2),
+      JSON.stringify(
+        values['content-review']
+          ? getContentReviewSchema()
+          : values.map
+            ? getMapSchema()
+            : values.record
+              ? getRecordSchema()
+              : getContributionSchema(),
+        null,
+        2,
+      ),
     );
   else if (command === 'check' && path && !extra.length) {
     const file = await open(path, 'r');
@@ -41,11 +69,11 @@ try {
     } finally {
       await file.close();
     }
-    if (values.record) assertTypeRecord(value);
+    if (values['content-review']) assertContentReviewRequest(value);
+    else if (values.map) assertMapDocument(value);
+    else if (values.record) assertTypeRecord(value);
     else assertContribution(value);
-    console.log(
-      'Valid MailSchema ' + (values.record ? 'type record' : 'contribution') + ' structure.',
-    );
+    console.log(`Valid MailSchema ${selected}.`);
   } else throw new Error(help);
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/dist/content-review-0.1.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mailschema.org/schemas/content-review-0.1.schema.json",
+  "title": "Content Review 0.1 MAP request",
+  "allOf": [
+    { "$ref": "https://mailschema.org/schemas/map-0.1.schema.json#/$defs/request" },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "object",
+          "properties": {
+            "id": { "const": "https://mailschema.org/types/content-review" },
+            "version": { "const": "0.1" },
+            "recordDigest": {
+              "const": "sha-256:0e6365df1bf904f2475f972ec66a5561edc0bfaae69fd7a1b41f53b40bf8ac1c"
+            }
+          }
+        }
+      }
+    },
+    {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "request-changes" },
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "feedback": { "type": "string", "minLength": 1, "maxLength": 12000 }
+              },
+              "required": ["feedback"]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "approve" },
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "maxProperties": 0
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

package/dist/contribution.schema.json

@@ -69,6 +69,11 @@
             "type": "object",
             "additionalProperties": false,
             "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+                "maxLength": 100
+              },
               "name": {
                 "type": "string",
                 "minLength": 1,
@@ -82,7 +87,7 @@
                 "pattern": "\\S"
               }
             },
-            "required": ["name", "description"]
+            "required": ["id", "name", "description"]
           },
           "minItems": 1,
           "maxItems": 100
@@ -188,6 +193,11 @@
             "type": "object",
             "additionalProperties": false,
             "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+                "maxLength": 100
+              },
               "name": {
                 "type": "string",
                 "minLength": 1,
@@ -332,6 +342,11 @@
             "type": "object",
             "additionalProperties": false,
             "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+                "maxLength": 100
+              },
               "name": {
                 "type": "string",
                 "minLength": 1,
@@ -345,7 +360,7 @@
                 "pattern": "\\S"
               }
             },
-            "required": ["name", "description"]
+            "required": ["id", "name", "description"]
           },
           "minItems": 1,
           "maxItems": 100
@@ -790,9 +805,8 @@
           "type": "array",
           "items": {
             "type": "string",
-            "minLength": 1,
-            "maxLength": 240,
-            "pattern": "\\S"
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 100
           },
           "minItems": 1,
           "maxItems": 100

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { contributionErrors, assertContribution, assertTypeRecord, referenceErro
 export type { CatalogView } from './validation.js';
 export { typeStages } from './model.js';
 export type { Party, TypeDefinition, TypeRecord, Contribution, Implementation } from './model.js';
+export { mapErrors, assertMapDocument, contentReviewRequestErrors, assertContentReviewRequest, getMapSchema, getContentReviewSchema, } from './map.js';
 /** Return an independent copy of the contribution JSON Schema (Draft 2020-12). */
 export declare function getContributionSchema(): Record<string, unknown>;
 /** Return the schema for an expanded Registry record, including attribution and history. */

package/dist/index.js

@@ -1,7 +1,8 @@
-/** Tools for preparing MailSchema Registry contributions. */
+/** Schemas and validation tools for MAP documents and MailSchema Registry contributions. */
 import schema from './contribution.schema.json' with { type: 'json' };
 export { contributionErrors, assertContribution, assertTypeRecord, referenceErrors, } from './validation.js';
 export { typeStages } from './model.js';
+export { mapErrors, assertMapDocument, contentReviewRequestErrors, assertContentReviewRequest, getMapSchema, getContentReviewSchema, } from './map.js';
 /** Return an independent copy of the contribution JSON Schema (Draft 2020-12). */
 export function getContributionSchema() {
     return structuredClone(schema);

package/dist/map-0.1.schema.json

@@ -0,0 +1,275 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mailschema.org/schemas/map-0.1.schema.json",
+  "title": "Mail Action Protocol 0.1",
+  "description": "Description, request, result and problem documents for the MAP 0.1 authenticated HTTPS profile.",
+  "oneOf": [
+    { "$ref": "#/$defs/description" },
+    { "$ref": "#/$defs/request" },
+    { "$ref": "#/$defs/result" },
+    { "$ref": "#/$defs/problem" }
+  ],
+  "$defs": {
+    "profile": {
+      "const": "https://mailschema.org/profiles/map/0.1"
+    },
+    "identifier": {
+      "type": "string",
+      "format": "uri",
+      "maxLength": 2048
+    },
+    "uuidUrn": {
+      "type": "string",
+      "pattern": "^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha-256:[a-f0-9]{64}$"
+    },
+    "recordDigest": {
+      "type": "string",
+      "pattern": "^sha-256:[a-f0-9]{64}$"
+    },
+    "typeReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+(?:\\.[0-9]+)?(?:-[a-zA-Z0-9.-]+)?$",
+          "maxLength": 80
+        },
+        "recordDigest": { "$ref": "#/$defs/recordDigest" }
+      },
+      "required": ["id", "version", "recordDigest"]
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "revision": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "title": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "digest": { "$ref": "#/$defs/digest" }
+      },
+      "required": ["id", "revision", "digest"]
+    },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+          "maxLength": 100
+        },
+        "name": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+        "inputSchema": { "$ref": "#/$defs/identifier" }
+      },
+      "required": ["id", "name", "description", "inputSchema"]
+    },
+    "description": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "@context": {
+          "const": "https://mailschema.org/contexts/map-0.1.jsonld"
+        },
+        "@type": { "const": "MailAction" },
+        "@id": { "$ref": "#/$defs/uuidUrn" },
+        "profile": { "$ref": "#/$defs/profile" },
+        "type": { "$ref": "#/$defs/typeReference" },
+        "describedAt": { "type": "string", "format": "date-time" },
+        "expiresAt": { "type": "string", "format": "date-time" },
+        "service": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": { "$ref": "#/$defs/identifier" },
+            "name": { "type": "string", "minLength": 1, "maxLength": 240 },
+            "execution": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "url": { "$ref": "#/$defs/identifier" },
+                "method": { "const": "POST" },
+                "requestMediaType": { "const": "application/json" },
+                "resultMediaType": { "const": "application/json" },
+                "resultUrlTemplate": {
+                  "type": "string",
+                  "format": "uri-template",
+                  "pattern": "^https://.*\\{requestId\\}.*$",
+                  "maxLength": 2048
+                },
+                "resultRetentionSeconds": {
+                  "type": "integer",
+                  "minimum": 300,
+                  "maximum": 31536000
+                }
+              },
+              "required": [
+                "url",
+                "method",
+                "requestMediaType",
+                "resultMediaType",
+                "resultUrlTemplate",
+                "resultRetentionSeconds"
+              ]
+            },
+            "humanUrl": { "$ref": "#/$defs/identifier" },
+            "authorization": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "kind": { "const": "service-configured" },
+                "schemes": {
+                  "type": "array",
+                  "items": { "enum": ["oauth2", "bearer", "session"] },
+                  "minItems": 1,
+                  "uniqueItems": true
+                },
+                "audience": { "type": "string", "minLength": 1, "maxLength": 500 }
+              },
+              "required": ["kind", "schemes"]
+            }
+          },
+          "required": ["id", "name", "execution", "humanUrl", "authorization"]
+        },
+        "target": { "$ref": "#/$defs/target" },
+        "operations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/operation" },
+          "minItems": 1,
+          "maxItems": 100
+        }
+      },
+      "required": [
+        "@context",
+        "@type",
+        "@id",
+        "profile",
+        "type",
+        "describedAt",
+        "expiresAt",
+        "service",
+        "target",
+        "operations"
+      ]
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "const": "MapRequest" },
+        "profile": { "$ref": "#/$defs/profile" },
+        "requestId": { "$ref": "#/$defs/uuidUrn" },
+        "interactionId": { "$ref": "#/$defs/uuidUrn" },
+        "requestedAt": { "type": "string", "format": "date-time" },
+        "type": { "$ref": "#/$defs/typeReference" },
+        "operation": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+          "maxLength": 100
+        },
+        "target": { "$ref": "#/$defs/target" },
+        "input": { "type": "object", "maxProperties": 100 }
+      },
+      "required": [
+        "kind",
+        "profile",
+        "requestId",
+        "interactionId",
+        "requestedAt",
+        "type",
+        "operation",
+        "target",
+        "input"
+      ]
+    },
+    "result": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "const": "MapResult" },
+        "profile": { "$ref": "#/$defs/profile" },
+        "requestId": { "$ref": "#/$defs/uuidUrn" },
+        "interactionId": { "$ref": "#/$defs/uuidUrn" },
+        "operation": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+          "maxLength": 100
+        },
+        "state": { "enum": ["accepted", "completed", "pending", "approval-required"] },
+        "target": { "$ref": "#/$defs/target" },
+        "recordedAt": { "type": "string", "format": "date-time" },
+        "resultUrl": { "$ref": "#/$defs/identifier" },
+        "output": { "type": "object", "maxProperties": 100 }
+      },
+      "required": [
+        "kind",
+        "profile",
+        "requestId",
+        "interactionId",
+        "operation",
+        "state",
+        "target",
+        "recordedAt",
+        "resultUrl",
+        "output"
+      ]
+    },
+    "problem": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "enum": [
+            "https://mailschema.org/problems/refused",
+            "https://mailschema.org/problems/stale-target",
+            "https://mailschema.org/problems/expired-interaction",
+            "https://mailschema.org/problems/invalid-request",
+            "https://mailschema.org/problems/unsupported-profile",
+            "https://mailschema.org/problems/unsupported-type",
+            "https://mailschema.org/problems/unsupported-operation",
+            "https://mailschema.org/problems/idempotency-conflict",
+            "https://mailschema.org/problems/request-in-progress"
+          ]
+        },
+        "title": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "status": { "type": "integer", "minimum": 400, "maximum": 599 },
+        "detail": { "type": "string", "minLength": 1, "maxLength": 4000 },
+        "instance": { "$ref": "#/$defs/identifier" },
+        "profile": { "$ref": "#/$defs/profile" },
+        "requestId": { "$ref": "#/$defs/uuidUrn" },
+        "interactionId": { "$ref": "#/$defs/uuidUrn" },
+        "code": {
+          "enum": [
+            "refused",
+            "stale-target",
+            "expired-interaction",
+            "invalid-request",
+            "unsupported-profile",
+            "unsupported-type",
+            "unsupported-operation",
+            "idempotency-conflict",
+            "request-in-progress"
+          ]
+        },
+        "target": { "$ref": "#/$defs/target" }
+      },
+      "required": [
+        "type",
+        "title",
+        "status",
+        "detail",
+        "instance",
+        "profile",
+        "requestId",
+        "interactionId",
+        "code"
+      ]
+    }
+  }
+}

package/dist/map.d.ts

@@ -0,0 +1,6 @@
+export declare function mapErrors(value: unknown): string[];
+export declare function assertMapDocument(value: unknown): void;
+export declare function contentReviewRequestErrors(value: unknown): string[];
+export declare function assertContentReviewRequest(value: unknown): void;
+export declare function getMapSchema(): Record<string, unknown>;
+export declare function getContentReviewSchema(): Record<string, unknown>;

package/dist/map.js

@@ -0,0 +1,35 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import mapSchema from './map-0.1.schema.json' with { type: 'json' };
+import contentReviewSchema from './content-review-0.1.schema.json' with { type: 'json' };
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false });
+addFormats(ajv);
+const mapDocument = ajv.compile(mapSchema);
+const contentReviewRequest = ajv.compile(contentReviewSchema);
+function errors(validate, value) {
+    if (validate(value))
+        return [];
+    return (validate.errors || []).map((error) => `${error.instancePath || '/'} ${error.message}${error.keyword === 'required' ? `: ${error.params.missingProperty}` : ''}`);
+}
+export function mapErrors(value) {
+    return errors(mapDocument, value);
+}
+export function assertMapDocument(value) {
+    const found = mapErrors(value);
+    if (found.length)
+        throw new Error(`Invalid MAP 0.1 document:\n${found.join('\n')}`);
+}
+export function contentReviewRequestErrors(value) {
+    return errors(contentReviewRequest, value);
+}
+export function assertContentReviewRequest(value) {
+    const found = contentReviewRequestErrors(value);
+    if (found.length)
+        throw new Error(`Invalid Content Review 0.1 request:\n${found.join('\n')}`);
+}
+export function getMapSchema() {
+    return structuredClone(mapSchema);
+}
+export function getContentReviewSchema() {
+    return structuredClone(contentReviewSchema);
+}

package/dist/model.d.ts

@@ -26,6 +26,7 @@ export interface TypeDefinition {
     overview: string;
     target: string;
     operations: {
+        id: string;
         name: string;
         description: string;
     }[];

package/dist/validation.js

@@ -39,7 +39,7 @@ export function referenceErrors(input, catalog) {
             ];
         if (target.profile !== input.profile)
             errors.push('Execution profile does not match the targeted record.');
-        const operations = new Set(target.operations.map((operation) => operation.name));
+        const operations = new Set(target.operations.map((operation) => operation.id));
         if (new Set(input.operations).size !== input.operations.length ||
             input.operations.some((operation) => !operations.has(operation)))
             errors.push('Unknown or duplicate operation in the implementation declaration.');
@@ -53,8 +53,11 @@ export function referenceErrors(input, catalog) {
         if (catalog.types.some((item) => item.record.slug !== input.record.slug &&
             item.record.name.toLocaleLowerCase() === input.record.name.toLocaleLowerCase()))
             errors.push('Another type already uses this name.');
-        const operations = input.record.operations.map((operation) => operation.name.toLocaleLowerCase());
-        if (new Set(operations).size !== operations.length)
+        const operationIds = input.record.operations.map((operation) => operation.id);
+        const operationNames = input.record.operations.map((operation) => operation.name.toLocaleLowerCase());
+        if (new Set(operationIds).size !== operationIds.length)
+            errors.push('Operation identifiers must be unique within a type.');
+        if (new Set(operationNames).size !== operationNames.length)
             errors.push('Operation names must be unique within a type.');
     }
     return errors;

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "mailschema",
-  "version": "0.1.0",
-  "description": "JSON Schemas, TypeScript definitions and validation tools for MailSchema Registry contributions",
+  "version": "0.1.1",
+  "description": "Schemas and validation tools for Mail Action Protocol and the MailSchema Registry",
   "type": "module",
   "license": "MIT",
   "author": "MailSchema contributors",
+  "homepage": "https://mailschema.org/tools/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mailschema/mailschema.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mailschema/mailschema/issues"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -14,15 +22,17 @@
       "import": "./dist/index.js"
     },
     "./contribution.schema.json": "./dist/contribution.schema.json",
+    "./map-0.1.schema.json": "./dist/map-0.1.schema.json",
+    "./content-review-0.1.schema.json": "./dist/content-review-0.1.schema.json",
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
   "bin": {
-    "mailschema": "./cli.mjs"
+    "mailschema": "./bin/mailschema.js"
   },
   "files": [
     "dist",
-    "cli.mjs",
+    "bin",
     "README.md",
     "LICENSE"
   ],