@crombolo/schema 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/schema",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Schema-as-code for crombolo: TOML document, media and member type definitions.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.11.0",
-    "@crombolo/data": "0.11.0"
+    "@crombolo/core": "0.12.1",
+    "@crombolo/data": "0.12.1"
   }
 }

package/src/check.ts

@@ -17,6 +17,9 @@ import {
   latestPreparedState,
   pendingMigrations,
   readLedger,
+  SYSTEM_CONTENT_TYPES,
+  SYSTEM_MEDIA_TYPES,
+  SYSTEM_MEMBER_TYPE,
 } from '@crombolo/data'
 import { BUILTIN_DATA_TYPES, storageTypeFor } from './builtin.ts'
 import type { LoadedSchema } from './load.ts'
@@ -213,26 +216,56 @@ export async function runCheck(
   const ledgered = new Set(ledger.filter((r) => r.kind === 'value').map((r) => r.name))
   const prepared = await latestPreparedState(db)
 
-  // ---- types removed while they have content
-  const inFiles = new Set(loaded.set.contentTypes.map((t) => t.alias))
-  const dbTypes = await db.query<{ unique_id: string; alias: string }>(
-    'SELECT n.unique_id, ct.alias FROM content_type ct JOIN node n ON n.id = ct.node_id WHERE ct.retired_at IS NULL',
-  )
-  for (const row of dbTypes) {
-    if (inFiles.has(String(row.alias))) continue
-    const count = await types.contentCount(String(row.unique_id).toLowerCase())
-    if (count === 0) continue
-    findings.push({
-      kind: 'blocking',
-      code: 'type-removed-with-content',
-      subjectType: 'document-type',
-      subjectKey: String(row.unique_id).toLowerCase(),
-      subjectName: String(row.alias),
-      propertyAlias: null,
-      culture: null,
-      message: `content type "${row.alias}" was removed from schema/ but ${count} document(s) of it exist`,
-      link: null,
-    })
+  // ---- types removed while they have content; the shipped types need no file
+  const shipped = new Set([
+    ...SYSTEM_MEDIA_TYPES.map((t) => t.key),
+    ...SYSTEM_CONTENT_TYPES.map((t) => t.key),
+    SYSTEM_MEMBER_TYPE.key,
+  ])
+  const kinds = [
+    {
+      kind: 'document' as const,
+      files: loaded.set.contentTypes,
+      noun: 'content type',
+      items: 'document(s)',
+    },
+    {
+      kind: 'media' as const,
+      files: loaded.set.mediaTypes ?? [],
+      noun: 'media type',
+      items: 'media item(s)',
+    },
+    {
+      kind: 'member' as const,
+      files: loaded.set.memberTypes ?? [],
+      noun: 'member type',
+      items: 'member(s)',
+    },
+  ]
+  for (const { kind, files, noun, items } of kinds) {
+    const repo = kind === 'document' ? types : new ContentTypeRepository(db, { kind })
+    const inFiles = new Set(files.map((t) => t.alias.toLowerCase()))
+    const dbTypes = await db.query<{ unique_id: string; alias: string }>(
+      'SELECT n.unique_id, ct.alias FROM content_type ct JOIN node n ON n.id = ct.node_id WHERE ct.retired_at IS NULL AND n.node_object_type = ?',
+      [repo.objectType],
+    )
+    for (const row of dbTypes) {
+      const key = String(row.unique_id).toLowerCase()
+      if (inFiles.has(String(row.alias).toLowerCase()) || shipped.has(key)) continue
+      const count = await repo.contentCount(key)
+      if (count === 0) continue
+      findings.push({
+        kind: 'blocking',
+        code: 'type-removed-with-content',
+        subjectType: `${kind}-type` as const,
+        subjectKey: key,
+        subjectName: String(row.alias),
+        propertyAlias: null,
+        culture: null,
+        message: `${noun} "${row.alias}" was removed from schema/ but ${count} ${items} of it exist`,
+        link: null,
+      })
+    }
   }
 
   // ---- properties that need data: newly mandatory, or changing editor

package/src/export.ts

@@ -18,6 +18,7 @@ import {
   type Db,
   FolderRepository,
   LanguageRepository,
+  readUrlOptions,
   SYSTEM_CONTENT_TYPES,
   SYSTEM_MEDIA_TYPES,
 } from '@crombolo/data'
@@ -188,6 +189,7 @@ function isUnchangedBuiltin(dataType: SchemaDataType): boolean {
 
 /** Every live definition in the database as a schema set; keys are always present. */
 export async function exportSchemaSet(db: Db, version: string): Promise<SchemaSet> {
+  const urls = await readUrlOptions(db)
   const types = new ContentTypeRepository(db)
   const dataTypes = new DataTypeRepository(db)
   const templates = new ComponentRepository(db)
@@ -330,6 +332,7 @@ export async function exportSchemaSet(db: Db, version: string): Promise<SchemaSe
     memberTypes,
     dataTypes: exportedDataTypes,
     languages,
+    ...(urls.hideTopLevel ? {} : { urls }),
   }
 }
 
@@ -342,7 +345,7 @@ export function writeSchemaFiles(schemaDir: string, set: SchemaSet): string[] {
     writeFileSync(file, content)
     written.push(file)
   }
-  put('schema.toml', writeSchemaVersion(set.version))
+  put('schema.toml', writeSchemaVersion(set.version, set.urls))
   for (const t of set.contentTypes)
     put(join(TYPE_KIND_FILES.document.dir, fileNameFor(t.alias)), writeContentType(t))
   for (const t of set.mediaTypes ?? [])

package/src/forms.ts

@@ -1,328 +1,34 @@
 /**
- * The form model, and the closed set of field types it may use.
- *
- * A form definition is structure, so it is a file like every other type
- * (`docs/forms.md`). Field types are an internal registry rather than an
- * extension point: the TOML vocabulary, the validator, the renderer and the
- * entry value shape all have to agree, and freezing that contract before
- * anything has stressed it would be a promise made too early.
+ * The form model and its closed set of field types. It lives in `@crombolo/core`,
+ * which the renderer shares; re-exported here for the schema package's users.
  */
-
-export type FormFieldType =
-  | 'shortAnswer'
-  | 'longAnswer'
-  | 'email'
-  | 'number'
-  | 'date'
-  | 'checkbox'
-  | 'dropdown'
-  | 'singleChoice'
-  | 'multipleChoice'
-  | 'fileUpload'
-  | 'dataConsent'
-  | 'titleAndDescription'
-  | 'richText'
-  | 'hidden'
-
-/** How a submitted value is stored, which decides how an entry reads it back. */
-export type FormValueKind = 'string' | 'strings' | 'number' | 'boolean' | 'files' | 'none'
-
-export interface FormFieldTypeInfo {
-  type: FormFieldType
-  label: string
-  stores: FormValueKind
-  /** Whether a choice list (`values`) applies, and is required. */
-  choices: boolean
-  /**
-   * Collects nothing: a caption and some text on the page. Never mandatory,
-   * never in an export, and never a condition's subject.
-   */
-  presentational: boolean
-  /** The settings this type accepts beyond the ones every field has. */
-  settings: readonly FormFieldSetting[]
-}
-
-export type FormFieldSetting =
-  | 'placeholder'
-  | 'maxlength'
-  | 'rows'
-  | 'min'
-  | 'max'
-  | 'step'
-  | 'accept'
-  | 'max-size-kb'
-  | 'content'
-  | 'default-value'
-  | 'multiple'
-
-const TEXTUAL = ['placeholder', 'maxlength', 'default-value'] as const
-
-export const FORM_FIELD_TYPES: readonly FormFieldTypeInfo[] = [
-  {
-    type: 'shortAnswer',
-    label: 'Short answer',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: TEXTUAL,
-  },
-  {
-    type: 'longAnswer',
-    label: 'Long answer',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: [...TEXTUAL, 'rows'],
-  },
-  {
-    type: 'email',
-    label: 'Email address',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: TEXTUAL,
-  },
-  {
-    type: 'number',
-    label: 'Number',
-    stores: 'number',
-    choices: false,
-    presentational: false,
-    settings: ['placeholder', 'min', 'max', 'step', 'default-value'],
-  },
-  {
-    type: 'date',
-    label: 'Date',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: ['min', 'max', 'default-value'],
-  },
-  {
-    type: 'checkbox',
-    label: 'Checkbox',
-    stores: 'boolean',
-    choices: false,
-    presentational: false,
-    settings: ['default-value'],
-  },
-  {
-    type: 'dropdown',
-    label: 'Dropdown',
-    stores: 'string',
-    choices: true,
-    presentational: false,
-    settings: ['default-value'],
-  },
-  {
-    type: 'singleChoice',
-    label: 'Single choice',
-    stores: 'string',
-    choices: true,
-    presentational: false,
-    settings: ['default-value'],
-  },
-  {
-    type: 'multipleChoice',
-    label: 'Multiple choice',
-    stores: 'strings',
-    choices: true,
-    presentational: false,
-    settings: [],
-  },
-  {
-    type: 'fileUpload',
-    label: 'File upload',
-    stores: 'files',
-    choices: false,
-    presentational: false,
-    settings: ['accept', 'max-size-kb', 'multiple'],
-  },
-  {
-    // Mandatory by default: a consent field that can be skipped is not consent.
-    type: 'dataConsent',
-    label: 'Data consent',
-    stores: 'boolean',
-    choices: false,
-    presentational: false,
-    settings: [],
-  },
-  {
-    type: 'titleAndDescription',
-    label: 'Title and description',
-    stores: 'none',
-    choices: false,
-    presentational: true,
-    settings: ['content'],
-  },
-  {
-    type: 'richText',
-    label: 'Rich text',
-    stores: 'none',
-    choices: false,
-    presentational: true,
-    settings: ['content'],
-  },
-  {
-    type: 'hidden',
-    label: 'Hidden',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: ['default-value'],
-  },
-]
-
-const BY_TYPE = new Map(FORM_FIELD_TYPES.map((info) => [info.type, info]))
-
-export function formFieldType(type: string): FormFieldTypeInfo | undefined {
-  return BY_TYPE.get(type as FormFieldType)
-}
-
-export const FORM_FIELD_TYPE_NAMES: readonly string[] = FORM_FIELD_TYPES.map((info) => info.type)
-
-/** Password is absent on purpose: a form that collects one should not exist. */
-export type FormConditionOperator =
-  | 'is'
-  | 'isNot'
-  | 'contains'
-  | 'doesNotContain'
-  | 'startsWith'
-  | 'endsWith'
-  | 'greaterThan'
-  | 'lessThan'
-  | 'isEmpty'
-  | 'isNotEmpty'
-
-export const FORM_CONDITION_OPERATORS: readonly FormConditionOperator[] = [
-  'is',
-  'isNot',
-  'contains',
-  'doesNotContain',
-  'startsWith',
-  'endsWith',
-  'greaterThan',
-  'lessThan',
-  'isEmpty',
-  'isNotEmpty',
-]
-
-/** The two operators that take no value, because the value is the emptiness. */
-export const VALUELESS_OPERATORS: readonly FormConditionOperator[] = ['isEmpty', 'isNotEmpty']
-
-export interface FormConditionRule {
-  /** Another field's alias, which must appear before this one. */
-  field: string
-  operator: FormConditionOperator
-  value?: string
-}
-
-export interface FormCondition {
-  action: 'show' | 'hide'
-  match: 'all' | 'any'
-  rules: FormConditionRule[]
-}
-
-export interface SchemaFormField {
-  key?: string
-  alias: string
-  type: FormFieldType
-  caption: string
-  helpText?: string
-  mandatory: boolean
-  mandatoryMessage?: string
-  /** A regular expression the value must match, and what to say when it does not. */
-  pattern?: string
-  patternMessage?: string
-  /** Hidden from anyone without the sensitive-data permission, in the API and in exports. */
-  sensitive: boolean
-  cssClass?: string
-  autocomplete?: string
-  /** A choice list, for the types that take one. */
-  values: string[]
-  placeholder?: string
-  defaultValue?: string
-  content?: string
-  maxlength?: number
-  rows?: number
-  min?: number
-  max?: number
-  step?: number
-  accept: string[]
-  maxSizeKb?: number
-  multiple?: boolean
-  condition?: FormCondition
-}
-
-export interface SchemaFormGroup {
-  caption?: string
-  /** A simple column count; the renderer lays the fields out across it. */
-  columns: number
-  fields: SchemaFormField[]
-  condition?: FormCondition
-}
-
-export interface SchemaFormPage {
-  caption?: string
-  groups: SchemaFormGroup[]
-  condition?: FormCondition
-}
-
-export type FormWorkflowType = 'sendEmail' | 'saveAsContent' | 'sendToUrl'
-
-export const FORM_WORKFLOW_TYPES: readonly FormWorkflowType[] = [
-  'sendEmail',
-  'saveAsContent',
-  'sendToUrl',
-]
-
-/** The state transition a workflow runs on. */
-export type FormWorkflowTrigger = 'submit' | 'approve'
-
-export interface SchemaFormWorkflow {
-  key?: string
-  type: FormWorkflowType
-  name: string
-  on: FormWorkflowTrigger
-  /** Per-type, so it is checked by the validator rather than by the shape. */
-  settings: Record<string, unknown>
-}
-
-export interface SchemaForm {
-  key?: string
-  alias: string
-  name: string
-  notes?: string
-  /** Whether a submission is kept. Off makes the form fire workflows and store nothing. */
-  storeEntries: boolean
-  /** Entries wait as `submitted` until someone approves them. */
-  requiresApproval: boolean
-  submitLabel?: string
-  nextLabel?: string
-  previousLabel?: string
-  /** Shown in place of the form after a submission, when there is no redirect. */
-  messageOnSubmit?: string
-  /** A document key to send the visitor to instead of showing a message. */
-  redirectTo?: string
-  /** A theme directory under `components/Forms/`. */
-  theme?: string
-  /** A field real visitors never fill; a filled one is marked as spam. */
-  honeypot: boolean
-  /** A submission faster than this is marked as spam. */
-  minimumSubmitSeconds?: number
-  /** Refused once this many entries exist, for a form with a hard cap. */
-  maxEntries?: number
-  since?: string
-  pages: SchemaFormPage[]
-  workflows: SchemaFormWorkflow[]
-}
-
-/** Every field in a form, in the order a visitor meets them. */
-export function allFormFields(form: SchemaForm): SchemaFormField[] {
-  return form.pages.flatMap((page) => page.groups.flatMap((group) => group.fields))
-}
-
-/** Every field that stores something, which is what an entry and an export carry. */
-export function storingFormFields(form: SchemaForm): SchemaFormField[] {
-  return allFormFields(form).filter((field) => formFieldType(field.type)?.stores !== 'none')
-}
+export {
+  allFormFields,
+  CHOICE_SOURCE_KINDS,
+  type ChoiceOption,
+  type ChoiceSource,
+  type ChoiceSourceKind,
+  choiceOptions,
+  FORM_CONDITION_OPERATORS,
+  FORM_FIELD_TYPE_NAMES,
+  FORM_FIELD_TYPES,
+  FORM_WORKFLOW_TYPES,
+  type FormCondition,
+  type FormConditionOperator,
+  type FormConditionRule,
+  type FormFieldSetting,
+  type FormFieldType,
+  type FormFieldTypeInfo,
+  type FormValueKind,
+  type FormWorkflowTrigger,
+  type FormWorkflowType,
+  formFieldType,
+  type SchemaForm,
+  type SchemaFormField,
+  type SchemaFormGroup,
+  type SchemaFormPage,
+  type SchemaFormWorkflow,
+  storingFormFields,
+  VALUELESS_OPERATORS,
+  withResolvedChoices,
+} from '@crombolo/core'

package/src/load.ts

@@ -4,9 +4,11 @@
  * The hash is over canonical serialisations, sorted — so it does not change
  * with file order, whitespace or comments, only with meaning.
  */
+
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import type { FormTypes } from '@crombolo/core'
 import type { SchemaForm } from './forms.ts'
 import type {
   SchemaContentType,
@@ -14,6 +16,7 @@ import type {
   SchemaLanguage,
   SchemaProblem,
   SchemaSet,
+  SchemaUrls,
 } from './model.ts'
 import { TYPE_KIND_FILES, typeFileKey } from './model.ts'
 import {
@@ -22,7 +25,7 @@ import {
   parseLanguages,
   parseMediaType,
   parseMemberType,
-  parseSchemaVersion,
+  parseSchemaSettings,
 } from './parse.ts'
 import { parseForm } from './parse-forms.ts'
 import {
@@ -49,22 +52,34 @@ function tomlFiles(dir: string): string[] {
     .map((name) => join(dir, name))
 }
 
-export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
+export interface LoadSchemaOptions {
+  /** The field and workflow types forms may use: the built-ins, and the wired bundles'. */
+  formTypes?: FormTypes
+}
+
+export function loadSchemaDirectory(
+  schemaDir: string,
+  options: LoadSchemaOptions = {},
+): LoadedSchema {
   const problems: SchemaProblem[] = []
   const files = new Map<string, string>()
   const contentTypes: SchemaContentType[] = []
   const dataTypes: SchemaDataType[] = []
   let languages: SchemaLanguage[] = []
   let version = '0'
+  let urls: SchemaUrls | undefined
 
   const rel = (file: string) =>
     file.startsWith(schemaDir) ? `schema${file.slice(schemaDir.length)}` : file
 
   const versionFile = join(schemaDir, 'schema.toml')
   if (existsSync(versionFile)) {
-    const parsed = parseSchemaVersion(rel(versionFile), readFileSync(versionFile, 'utf8'))
+    const parsed = parseSchemaSettings(rel(versionFile), readFileSync(versionFile, 'utf8'))
     problems.push(...parsed.problems)
-    if (parsed.value) version = parsed.value
+    if (parsed.value) {
+      version = parsed.value.version
+      urls = parsed.value.urls
+    }
   }
   for (const file of tomlFiles(join(schemaDir, TYPE_KIND_FILES.document.dir))) {
     const parsed = parseContentType(rel(file), readFileSync(file, 'utf8'))
@@ -102,7 +117,7 @@ export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
   }
   const forms: SchemaForm[] = []
   for (const file of tomlFiles(join(schemaDir, 'forms'))) {
-    const parsed = parseForm(rel(file), readFileSync(file, 'utf8'))
+    const parsed = parseForm(rel(file), readFileSync(file, 'utf8'), options.formTypes)
     problems.push(...parsed.problems)
     if (parsed.value) {
       forms.push(parsed.value)
@@ -116,7 +131,16 @@ export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
     if (parsed.value) languages = parsed.value
   }
   return {
-    set: { version, contentTypes, mediaTypes, memberTypes, dataTypes, languages, forms },
+    set: {
+      version,
+      contentTypes,
+      mediaTypes,
+      memberTypes,
+      dataTypes,
+      languages,
+      forms,
+      ...(urls ? { urls } : {}),
+    },
     problems,
     files,
   }
@@ -126,6 +150,8 @@ export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
 export function hashSchemaSet(set: SchemaSet): string {
   const parts = [
     `version:${set.version}`,
+    // Only when not the default, so every site hashed before this kept its hash.
+    ...(set.urls?.hideTopLevel === false ? ['urls:top-level-shown'] : []),
     ...set.contentTypes.map((t) => writeContentType(t)).sort(),
     ...(set.mediaTypes ?? []).map((t) => writeMediaType(t)).sort(),
     ...(set.memberTypes ?? []).map((t) => writeMemberType(t)).sort(),

package/src/model.ts

@@ -112,6 +112,14 @@ export interface SchemaSet {
   languages: SchemaLanguage[]
   /** `schema/forms/*.toml` — form definitions; see `docs/forms.md`. */
   forms?: SchemaForm[]
+  /** `[urls]` in schema/schema.toml; Umbraco's defaults when absent. */
+  urls?: SchemaUrls
+}
+
+/** How URLs are built, as Umbraco's `Umbraco:CMS:Global` settings set it. */
+export interface SchemaUrls {
+  /** `HideTopLevelNodeFromPath`: true, the default, leaves the top-level page out of paths. */
+  hideTopLevel: boolean
 }
 
 /** A problem found while parsing or validating, always locatable. */

package/src/parse-forms.ts

@@ -6,13 +6,16 @@
  * type and the two share nothing but the reader.
  */
 import {
+  BUILT_IN_FORM_TYPES,
+  type ChoiceSource,
+  type ChoiceSourceKind,
   FORM_CONDITION_OPERATORS,
-  FORM_FIELD_TYPE_NAMES,
-  FORM_WORKFLOW_TYPES,
   type FormCondition,
   type FormConditionOperator,
   type FormConditionRule,
   type FormFieldType,
+  type FormSettingValue,
+  type FormTypes,
   type FormWorkflowTrigger,
   type FormWorkflowType,
   formFieldType,
@@ -31,6 +34,7 @@ const FORM_KEYS = [
   'notes',
   'store-entries',
   'requires-approval',
+  'step-pages',
   'submit-label',
   'next-label',
   'previous-label',
@@ -59,6 +63,7 @@ const FIELD_KEYS = [
   'css-class',
   'autocomplete',
   'values',
+  'source',
   'placeholder',
   'default-value',
   'content',
@@ -70,10 +75,12 @@ const FIELD_KEYS = [
   'accept',
   'max-size-kb',
   'multiple',
+  'settings',
   'condition',
 ] as const
 const CONDITION_KEYS = ['action', 'match', 'rule'] as const
 const RULE_KEYS = ['field', 'operator', 'value'] as const
+const SOURCE_KEYS = ['kind', 'parent'] as const
 const WORKFLOW_KEYS = ['key', 'type', 'name', 'on', 'settings'] as const
 
 function condition(r: Reader, value: unknown, path: string): FormCondition | undefined {
@@ -112,14 +119,30 @@ function condition(r: Reader, value: unknown, path: string): FormCondition | und
   }
 }
 
-function field(r: Reader, t: Toml, path: string): SchemaFormField {
+/** Kept as written: the validator names an unknown kind, as it does an unknown type. */
+function source(r: Reader, value: unknown, path: string): ChoiceSource | undefined {
+  if (value === undefined) return undefined
+  const t = r.table(value, path)
+  if (!t) return undefined
+  r.unknown(t, SOURCE_KEYS, path)
+  return {
+    kind: (r.str(t, 'kind', path, true) ?? '') as ChoiceSourceKind,
+    parent: r.str(t, 'parent', path, true) ?? '',
+  }
+}
+
+/** Says a type is unknown by its name, and what is known: the built-ins, then each bundle's. */
+function unknownType(kind: 'field' | 'workflow', type: string, known: Iterable<string>): string {
+  return `the ${kind} type "${type}" is not built in, and no wired bundle provides it; expected one of ${[...known].join(', ')}`
+}
+
+function field(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormField {
   r.unknown(t, FIELD_KEYS, path)
   const type = r.str(t, 'type', path, true) ?? ''
-  if (type && !formFieldType(type))
-    r.problem(
-      `${path}.type`,
-      `unknown field type; expected one of ${FORM_FIELD_TYPE_NAMES.join(', ')}`,
-    )
+  if (type && !formFieldType(type, types))
+    r.problem(`${path}.type`, unknownType('field', type, types.fields.keys()))
+  const settings =
+    t.settings === undefined ? undefined : (r.table(t.settings, `${path}.settings`) ?? {})
   // Consent is mandatory unless the form says otherwise: a consent box that can
   // be skipped records agreement nobody gave.
   const mandatoryByDefault = type === 'dataConsent'
@@ -137,6 +160,7 @@ function field(r: Reader, t: Toml, path: string): SchemaFormField {
     cssClass: r.str(t, 'css-class', path),
     autocomplete: r.str(t, 'autocomplete', path),
     values: r.strs(t, 'values', path),
+    ...(t.source !== undefined ? { source: source(r, t.source, `${path}.source`) } : {}),
     placeholder: r.str(t, 'placeholder', path),
     defaultValue: r.str(t, 'default-value', path),
     content: r.str(t, 'content', path),
@@ -148,37 +172,39 @@ function field(r: Reader, t: Toml, path: string): SchemaFormField {
     accept: r.strs(t, 'accept', path),
     maxSizeKb: r.num(t, 'max-size-kb', path),
     ...(t.multiple !== undefined ? { multiple: r.bool(t, 'multiple', path, false) } : {}),
+    ...(settings ? { settings: settings as Record<string, FormSettingValue> } : {}),
     condition: condition(r, t.condition, `${path}.condition`),
   }
 }
 
-function group(r: Reader, t: Toml, path: string): SchemaFormGroup {
+function group(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormGroup {
   r.unknown(t, GROUP_KEYS, path)
   return {
     caption: r.str(t, 'caption', path),
     columns: r.num(t, 'columns', path) ?? 1,
-    fields: r.tables(t.field, `${path}.field`).map((f, i) => field(r, f, `${path}.field[${i}]`)),
+    fields: r
+      .tables(t.field, `${path}.field`)
+      .map((f, i) => field(r, f, `${path}.field[${i}]`, types)),
     condition: condition(r, t.condition, `${path}.condition`),
   }
 }
 
-function page(r: Reader, t: Toml, path: string): SchemaFormPage {
+function page(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormPage {
   r.unknown(t, PAGE_KEYS, path)
   return {
     caption: r.str(t, 'caption', path),
-    groups: r.tables(t.group, `${path}.group`).map((g, i) => group(r, g, `${path}.group[${i}]`)),
+    groups: r
+      .tables(t.group, `${path}.group`)
+      .map((g, i) => group(r, g, `${path}.group[${i}]`, types)),
     condition: condition(r, t.condition, `${path}.condition`),
   }
 }
 
-function workflow(r: Reader, t: Toml, path: string): SchemaFormWorkflow {
+function workflow(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormWorkflow {
   r.unknown(t, WORKFLOW_KEYS, path)
   const type = r.str(t, 'type', path, true) ?? ''
-  if (type && !FORM_WORKFLOW_TYPES.includes(type as FormWorkflowType))
-    r.problem(
-      `${path}.type`,
-      `unknown workflow type; expected one of ${FORM_WORKFLOW_TYPES.join(', ')}`,
-    )
+  if (type && !types.workflows.has(type))
+    r.problem(`${path}.type`, unknownType('workflow', type, types.workflows.keys()))
   const on = r.str(t, 'on', path) ?? 'submit'
   if (on !== 'submit' && on !== 'approve') r.problem(`${path}.on`, "expected 'submit' or 'approve'")
   const settings = t.settings === undefined ? {} : r.table(t.settings, `${path}.settings`)
@@ -191,7 +217,11 @@ function workflow(r: Reader, t: Toml, path: string): SchemaFormWorkflow {
   }
 }
 
-export function parseForm(file: string, source: string): ParseResult<SchemaForm> {
+export function parseForm(
+  file: string,
+  source: string,
+  types: FormTypes = BUILT_IN_FORM_TYPES,
+): ParseResult<SchemaForm> {
   const r = new Reader(file)
   const root = toml(source, r)
   if (!root) return { value: undefined, problems: r.problems }
@@ -212,6 +242,7 @@ export function parseForm(file: string, source: string): ParseResult<SchemaForm>
     // what people typed would be the worst possible default.
     storeEntries: r.bool(t, 'store-entries', path, true),
     requiresApproval: r.bool(t, 'requires-approval', path, false),
+    ...(t['step-pages'] !== undefined ? { stepPages: r.bool(t, 'step-pages', path, false) } : {}),
     submitLabel: r.str(t, 'submit-label', path),
     nextLabel: r.str(t, 'next-label', path),
     previousLabel: r.str(t, 'previous-label', path),
@@ -222,8 +253,10 @@ export function parseForm(file: string, source: string): ParseResult<SchemaForm>
     minimumSubmitSeconds: r.num(t, 'minimum-submit-seconds', path),
     maxEntries: r.num(t, 'max-entries', path),
     since: r.str(t, 'since', path),
-    pages: r.tables(root.page, 'page').map((p, i) => page(r, p, `page[${i}]`)),
-    workflows: r.tables(root.workflow, 'workflow').map((w, i) => workflow(r, w, `workflow[${i}]`)),
+    pages: r.tables(root.page, 'page').map((p, i) => page(r, p, `page[${i}]`, types)),
+    workflows: r
+      .tables(root.workflow, 'workflow')
+      .map((w, i) => workflow(r, w, `workflow[${i}]`, types)),
   }
   return { value: r.problems.length === 0 ? value : undefined, problems: r.problems }
 }

package/src/parse.ts

@@ -11,6 +11,7 @@ import {
   type SchemaProperty,
   type SchemaTab,
   type SchemaTypeKind,
+  type SchemaUrls,
   TYPE_KIND_FILES,
 } from './model.ts'
 import { type ParseResult, Reader, type Toml, toml } from './reader.ts'
@@ -251,12 +252,35 @@ export function parseLanguages(file: string, source: string): ParseResult<Schema
 }
 
 export function parseSchemaVersion(file: string, source: string): ParseResult<string> {
+  const parsed = parseSchemaSettings(file, source)
+  return { value: parsed.value?.version, problems: parsed.problems }
+}
+
+/** `schema/schema.toml`: the schema version, and how the site's URLs are built. */
+export function parseSchemaSettings(
+  file: string,
+  source: string,
+): ParseResult<{ version: string; urls?: SchemaUrls }> {
   const r = new Reader(file)
   const root = toml(source, r)
   if (!root) return { value: undefined, problems: r.problems }
-  r.unknown(root, ['schema'], '')
+  r.unknown(root, ['schema', 'urls'], '')
   const t = r.table(root.schema, 'schema')
   const version = t ? r.str(t, 'version', 'schema', true) : undefined
   if (t) r.unknown(t, ['version'], 'schema')
-  return { value: r.problems.length === 0 ? version : undefined, problems: r.problems }
+  let urls: SchemaUrls | undefined
+  if (root.urls !== undefined) {
+    const u = r.table(root.urls, 'urls')
+    if (u) {
+      r.unknown(u, ['hide-top-level'], 'urls')
+      urls = { hideTopLevel: r.bool(u, 'hide-top-level', 'urls', true) }
+    }
+  }
+  return {
+    value:
+      r.problems.length === 0 && version !== undefined
+        ? { version, ...(urls ? { urls } : {}) }
+        : undefined,
+    problems: r.problems,
+  }
 }

package/src/sync.ts

@@ -3,6 +3,7 @@
  * retirement, and a type with content refuses to disappear. The algorithm and
  * the multi-node rules are in docs/schema-as-code.md, "Synchronisation".
  */
+import type { FormTypes } from '@crombolo/core'
 import { type ContentTypeAggregate, ObjectTypes, type PropertyTypeModel } from '@crombolo/core'
 import {
   appendCacheInstruction,
@@ -15,6 +16,7 @@ import {
   DataTypeRepository,
   type Db,
   DbDate,
+  DEFAULT_URL_OPTIONS,
   FolderRepository,
   LanguageRepository,
   Locks,
@@ -25,7 +27,10 @@ import {
   SYSTEM_CONTENT_TYPES,
   SYSTEM_MEDIA_TYPES,
   SYSTEM_MEMBER_TYPE,
+  sameUrlOptions,
+  type UrlOptions,
   updateSchemaStateHash,
+  writeUrlOptions,
 } from '@crombolo/data'
 import { BUILTIN_DATA_TYPES, storageTypeFor, systemPropertyKeys } from './builtin.ts'
 import { hashSchemaSet, type LoadedSchema } from './load.ts'
@@ -56,6 +61,8 @@ export interface SyncOptions {
    * is pending everywhere until `upgrade` makes the state current. Default current.
    */
   status?: 'prepared' | 'current'
+  /** The form field and workflow types the site's wired bundles add. */
+  formTypes?: FormTypes
 }
 
 export type SyncAction = 'applied' | 'would-apply' | 'skipped-older' | 'skipped-same' | 'refused'
@@ -88,6 +95,8 @@ export interface SyncReport {
   revived: string[]
   assignedKeys: AssignedKey[]
   deferred: string[]
+  /** Set when the sync changed how URLs are built, so the old ones can be redirected. */
+  urls?: { before: UrlOptions; after: UrlOptions }
 }
 
 export const emptySyncReport = (
@@ -132,7 +141,10 @@ export async function syncSchema(
 ): Promise<SyncReport> {
   const problems = [
     ...loaded.problems,
-    ...validateSchemaSet(loaded.set, { componentAliases: options.componentAliases }),
+    ...validateSchemaSet(loaded.set, {
+      componentAliases: options.componentAliases,
+      types: options.formTypes,
+    }),
   ]
   if (problems.length > 0)
     return emptySyncReport('refused', { reason: 'the schema has problems', problems })
@@ -268,6 +280,14 @@ export async function syncSchema(
           report.updated.languages += result.updated
         }
 
+        // ---- how URLs are built: the files are the source, absent is the default.
+        // Only a current sync moves it; a prepared one serves no URLs yet.
+        if (status === 'current') {
+          const urls = { hideTopLevel: set.urls?.hideTopLevel ?? DEFAULT_URL_OPTIONS.hideTopLevel }
+          const before = await writeUrlOptions(tx, urls)
+          if (!sameUrlOptions(before, urls)) report.urls = { before, after: urls }
+        }
+
         // ---- templates referenced by types must have a row
         const componentKeyByAlias = new Map<string, string>()
         for (const alias of new Set(set.contentTypes.flatMap((t) => t.components))) {

package/src/validate-forms.ts

@@ -8,14 +8,20 @@
  */
 import {
   allFormFields,
+  BUILT_IN_FORM_TYPES,
+  CHOICE_SOURCE_KINDS,
   type FormCondition,
+  type FormTypes,
   formFieldType,
   type SchemaForm,
   type SchemaFormField,
+  settingsProblems,
   VALUELESS_OPERATORS,
 } from '@crombolo/core'
 import type { SchemaProblem } from './model.ts'
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
 const VERSION = /^\d+(\.\d+)*$/
 const ALIAS = /^[a-zA-Z][a-zA-Z0-9]*$/
 
@@ -45,6 +51,8 @@ export interface ValidateFormsOptions {
   formThemes?: ReadonlySet<string>
   /** Content type aliases, so `saveAsContent` can be held to a real one. */
   contentTypeAliases?: ReadonlySet<string>
+  /** The field and workflow types in play: the built-ins, and the wired bundles'. */
+  types?: FormTypes
 }
 
 export function validateForms(
@@ -98,7 +106,7 @@ export function validateForms(
         'requires store-entries, since there is no entry to approve',
       )
 
-    validateFields(form, file, add)
+    validateFields(form, file, options.types ?? BUILT_IN_FORM_TYPES, add)
     validateWorkflows(form, file, options, add)
   }
   return problems
@@ -106,7 +114,7 @@ export function validateForms(
 
 type Add = (file: string, path: string, message: string) => void
 
-function validateFields(form: SchemaForm, file: string, add: Add): void {
+function validateFields(form: SchemaForm, file: string, types: FormTypes, add: Add): void {
   const fields = allFormFields(form)
   const seen = new Set<string>()
   /** Aliases usable by a condition: a field may only look at earlier ones. */
@@ -121,7 +129,7 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
         add(file, 'page.group.columns', `${group.columns} is not a column count between 1 and 4`)
       for (const field of group.fields) {
         const path = `page.group.field[${index}]`
-        const info = formFieldType(field.type)
+        const info = formFieldType(field.type, types)
 
         if (!ALIAS.test(field.alias))
           add(
@@ -148,13 +156,40 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
                 `a ${field.type} field collects nothing, so it cannot be sensitive`,
               )
           }
-          if (info.choices && field.values.length === 0)
+          const { source } = field
+          if (source && field.values.length > 0)
+            add(
+              file,
+              `${path}.source`,
+              'a field takes its choices from values or from a source, not both',
+            )
+          if (source && !info.choices)
+            add(file, `${path}.source`, `a ${field.type} field has nothing to choose from`)
+          if (source && info.choices) {
+            if (!CHOICE_SOURCE_KINDS.includes(source.kind))
+              add(
+                file,
+                `${path}.source.kind`,
+                `"${source.kind}" is not a kind of source; expected one of ${CHOICE_SOURCE_KINDS.join(', ')}`,
+              )
+            if (source.kind === 'content' && !UUID.test(source.parent))
+              add(file, `${path}.source.parent`, 'a content source names its parent page by key')
+            if (source.kind === 'dictionary' && source.parent.trim() === '')
+              add(
+                file,
+                `${path}.source.parent`,
+                'a dictionary source names its parent dictionary item',
+              )
+          }
+          if (info.choices && !source && field.values.length === 0)
             add(file, `${path}.values`, `a ${field.type} field needs values to choose from`)
           if (!info.choices && field.values.length > 0)
             add(file, `${path}.values`, `a ${field.type} field has nothing to choose from`)
-          // A default has to be one of the choices, or the form opens invalid.
+          // A default has to be one of the choices, or the form opens invalid. A
+          // source's choices are only known once it is resolved, so not checked here.
           if (
             info.choices &&
+            !source &&
             field.defaultValue !== undefined &&
             !field.values.includes(field.defaultValue)
           )
@@ -165,6 +200,21 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
             if (!info.settings.includes(setting as never))
               add(file, `${path}.${setting}`, `does not apply to a ${field.type} field`)
           }
+          // A built-in type's settings are keys of the field; only a bundle's
+          // type has a settings table, held to what it declares.
+          if (!info.bundle && field.settings !== undefined)
+            add(
+              file,
+              `${path}.settings`,
+              `a ${field.type} field is built in and takes no settings table; its settings are keys of the field`,
+            )
+          if (info.bundle)
+            for (const message of settingsProblems(
+              info.declared,
+              field.settings ?? {},
+              `a ${field.type} field`,
+            ))
+              add(file, `${path}.settings`, message)
         }
 
         if (field.pattern !== undefined) {
@@ -184,19 +234,27 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
           add(file, `${path}.max-size-kb`, 'must be at least 1')
 
         if (field.condition)
-          validateCondition(field.condition, fields, earlier, file, `${path}.condition`, add)
+          validateCondition(field.condition, fields, earlier, file, `${path}.condition`, types, add)
         earlier.add(field.alias.toLowerCase())
         index++
       }
       if (group.condition)
-        validateCondition(group.condition, fields, earlier, file, 'page.group.condition', add)
+        validateCondition(
+          group.condition,
+          fields,
+          earlier,
+          file,
+          'page.group.condition',
+          types,
+          add,
+        )
     }
     if (page.condition)
-      validateCondition(page.condition, fields, earlier, file, 'page.condition', add)
+      validateCondition(page.condition, fields, earlier, file, 'page.condition', types, add)
   }
 
   if (fields.length === 0) add(file, 'page.group.field', 'a form needs at least one field')
-  else if (fields.every((field) => formFieldType(field.type)?.presentational))
+  else if (fields.every((field) => formFieldType(field.type, types)?.presentational))
     add(file, 'page.group.field', 'every field is presentational, so the form collects nothing')
 }
 
@@ -206,6 +264,7 @@ function validateCondition(
   earlier: ReadonlySet<string>,
   file: string,
   path: string,
+  types: FormTypes,
   add: Add,
 ): void {
   for (const [index, rule] of condition.rules.entries()) {
@@ -223,7 +282,7 @@ function validateCondition(
         `${rulePath}.field`,
         `"${rule.field}" comes later in the form, so it has no value to compare yet`,
       )
-    if (formFieldType(target.type)?.presentational)
+    if (formFieldType(target.type, types)?.presentational)
       add(file, `${rulePath}.field`, `"${rule.field}" collects nothing, so it cannot be compared`)
     const valueless = VALUELESS_OPERATORS.includes(rule.operator)
     if (valueless && rule.value !== undefined)
@@ -275,6 +334,15 @@ function validateWorkflows(
         'runs on approval, but the form does not require approval so nothing ever approves it',
       )
 
+    const bundled = (options.types ?? BUILT_IN_FORM_TYPES).workflows.get(workflow.type)
+    if (bundled?.bundle) {
+      const where = `a ${workflow.type} workflow`
+      const declared = settingsProblems(bundled.declared, workflow.settings, where)
+      for (const message of declared) add(file, `${path}.settings`, message)
+      const own = declared.length === 0 ? bundled.validate?.(workflow.settings) : undefined
+      if (own) add(file, `${path}.settings`, own)
+      continue
+    }
     const rules = WORKFLOW_SETTINGS[workflow.type]
     if (!rules) continue
     const allowed = new Set([...rules.required, ...rules.optional])

package/src/write-forms.ts

@@ -73,6 +73,8 @@ function writeField(out: string[], header: string, field: SchemaFormField): void
   line(out, 'css-class', field.cssClass)
   line(out, 'autocomplete', field.autocomplete)
   line(out, 'values', field.values, field.values.length > 0)
+  if (field.source)
+    out.push(`source = { kind = ${str(field.source.kind)}, parent = ${str(field.source.parent)} }`)
   line(out, 'placeholder', field.placeholder)
   line(out, 'default-value', field.defaultValue)
   line(out, 'content', field.content)
@@ -84,6 +86,12 @@ function writeField(out: string[], header: string, field: SchemaFormField): void
   line(out, 'accept', field.accept, field.accept.length > 0)
   line(out, 'max-size-kb', field.maxSizeKb)
   line(out, 'multiple', field.multiple)
+  const settings = Object.keys(field.settings ?? {}).sort()
+  // Inline, so a bundle type's settings stay inside the one field they belong to.
+  if (field.settings)
+    out.push(
+      `settings = { ${settings.map((key) => `${keyOf(key)} = ${scalar(field.settings?.[key])}`).join(', ')} }`,
+    )
   if (field.condition) writeCondition(out, `${header}.condition`, field.condition)
 }
 
@@ -123,6 +131,7 @@ export function writeForm(form: SchemaForm): string {
   line(out, 'notes', form.notes)
   line(out, 'store-entries', false, !form.storeEntries)
   line(out, 'requires-approval', true, form.requiresApproval)
+  line(out, 'step-pages', true, form.stepPages === true)
   line(out, 'submit-label', form.submitLabel)
   line(out, 'next-label', form.nextLabel)
   line(out, 'previous-label', form.previousLabel)

package/src/write.ts

@@ -12,6 +12,7 @@ import {
   type SchemaLanguage,
   type SchemaProperty,
   type SchemaTypeKind,
+  type SchemaUrls,
   TYPE_KIND_FILES,
 } from './model.ts'
 
@@ -162,8 +163,10 @@ export function writeLanguages(languages: readonly SchemaLanguage[]): string {
   return `${out.join('\n')}\n`
 }
 
-export function writeSchemaVersion(version: string): string {
-  return `[schema]\nversion = ${str(version)}\n`
+/** `schema/schema.toml`. `[urls]` is written only when it differs from Umbraco's defaults. */
+export function writeSchemaVersion(version: string, urls?: SchemaUrls): string {
+  const out = `[schema]\nversion = ${str(version)}\n`
+  return urls && !urls.hideTopLevel ? `${out}\n[urls]\nhide-top-level = false\n` : out
 }
 
 /** The canonical filename for an alias: kebab-case. */