@dforge-core/metadata 0.0.1 → 0.0.3

package/schemas/manifest.schema.json

@@ -0,0 +1,146 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/manifest.schema.json",
+	"title": "dForge Module Manifest",
+	"description": "Module package manifest defining metadata, dependencies, and entity references",
+	"type": "object",
+	"required": ["packageFormat", "moduleId", "code", "version", "dbSchemaVersion", "displayName"],
+	"properties": {
+		"packageFormat": {
+			"type": "integer",
+			"minimum": 1,
+			"description": "Package format version (currently 1)"
+		},
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+			"description": "Globally unique module UUID"
+		},
+		"code": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9_-]*$",
+			"description": "Human-readable module code (becomes schema name and module_cd in DB)"
+		},
+		"kind": {
+			"type": "string",
+			"enum": ["module", "pack"],
+			"default": "module",
+			"description": "Package kind. 'module' (default) — a regular module with its own entities/views/actions. 'pack' — a dependency bundle: installs a curated set of other modules via `dependencies` in order, owns no entities itself."
+		},
+		"version": {
+			"type": "string",
+			"pattern": "^\\d+\\.\\d+\\.\\d+",
+			"description": "Module version (semver)"
+		},
+		"dbSchemaVersion": {
+			"type": "string",
+			"pattern": "^\\d+\\.\\d+\\.\\d+",
+			"description": "Database schema version (semver)"
+		},
+		"displayName": {
+			"type": "string",
+			"description": "Human-readable module name"
+		},
+		"description": {
+			"type": "string",
+			"description": "Module description"
+		},
+		"schemaName": {
+			"type": "string",
+			"description": "Database schema name override (defaults to module code, system modules use 'dForge')"
+		},
+		"system": {
+			"type": "boolean",
+			"description": "System module flag (cannot be uninstalled, admin-only). Omit for regular modules."
+		},
+		"author": {
+			"type": "object",
+			"properties": {
+				"name": {
+					"type": "string",
+					"description": "Author name"
+				},
+				"url": {
+					"type": "string",
+					"description": "Author URL"
+				}
+			},
+			"required": ["name"],
+			"additionalProperties": false
+		},
+		"license": {
+			"type": "string",
+			"description": "License identifier (e.g. 'proprietary', 'MIT')"
+		},
+		"dependencies": {
+			"type": "object",
+			"description": "Module dependencies: module code → semver range OR { version, entities? } object for partial deps that only import specific entities from the dependency.",
+			"additionalProperties": {
+				"oneOf": [
+					{
+						"type": "string",
+						"description": "Semver version range (e.g. '>=1.0.0')"
+					},
+					{
+						"type": "object",
+						"required": ["version"],
+						"properties": {
+							"version": {
+								"type": "string",
+								"description": "Semver version range"
+							},
+							"entities": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Entity codes from the dependency that this module needs. If omitted, all entities are accessible."
+							}
+						},
+						"additionalProperties": false
+					}
+				]
+			}
+		},
+		"auditHistory": {
+			"type": "string",
+			"enum": ["none", "minimal", "full"],
+			"description": "Default audit history mode for entities in this module ('full' captures every field change; 'minimal' captures only inserts/deletes; 'none' disables). Individual entities can override."
+		},
+		"entities": {
+			"type": "object",
+			"description": "Entity definitions and extensions: entity code → relative path to entity JSON file. Dotted keys (e.g. 'fin.invoice') indicate extensions of other modules' entities (the entity file must have an 'extends' property).",
+			"additionalProperties": {
+				"type": "string",
+				"pattern": "^(\\./)?entities/.+\\.json$"
+			}
+		},
+		"category": {
+			"type": "string",
+			"description": "Module category for display (e.g. 'Integration', 'Finance')"
+		},
+		"tags": {
+			"type": "array",
+			"items": { "type": "string" },
+			"description": "Free-form tags for search and discovery (e.g. ['crm', 'sales', 'leads']). Convention: lowercase, hyphen-separated."
+		},
+		"icon": {
+			"type": "string",
+			"description": "Bootstrap icon class (e.g. 'bi-link-45deg')"
+		},
+		"supportedLocales": {
+			"type": "array",
+			"items": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$" },
+			"description": "Non-English locales the package promises to translate. Each entry MUST match a translations/<locale>.json file, and every translatable resource (entity/field labels, folders, views, menus + items, actions + params, reports + datasets + params, settings) MUST have a label in that file. English is the default — don't list 'en' or 'en-US'."
+		},
+		"created": {
+			"type": "string",
+			"format": "date",
+			"description": "Initial creation date of the module package (YYYY-MM-DD). Informational only; not enforced by the installer."
+		},
+		"updated": {
+			"type": "string",
+			"format": "date",
+			"description": "Last edit date of the manifest (YYYY-MM-DD). Informational; bump when shipping a new version."
+		}
+	},
+	"additionalProperties": false
+}

package/schemas/menus.schema.json

@@ -0,0 +1,86 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/menus.schema.json",
+	"title": "dForge Menus",
+	"description": "Menu definitions for a dForge module",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/menu"
+	},
+	"$defs": {
+		"menu": {
+			"type": "object",
+			"required": ["label", "items"],
+			"properties": {
+				"label": {
+					"type": "string",
+					"description": "Menu display name"
+				},
+				"description": {
+					"type": "string",
+					"description": "Optional description text (tooltip, subtitle)"
+				},
+				"folders": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Folder codes where this menu is available"
+				},
+				"items": {
+					"type": "object",
+					"description": "Menu items keyed by item code",
+					"additionalProperties": {
+						"$ref": "#/$defs/menuItem"
+					}
+				}
+			},
+			"additionalProperties": false
+		},
+		"menuItem": {
+			"type": "object",
+			"required": ["label"],
+			"properties": {
+				"itemType": {
+					"type": ["string", "null"],
+					"enum": ["V", "D", "R", null],
+					"description": "Item type: V=Data View, D=Document, R=Report, null=folder/section"
+				},
+				"dataViewCode": {
+					"type": "string",
+					"description": "Data view code (when itemType is 'V')"
+				},
+				"documentCode": {
+					"type": "string",
+					"description": "Document code (when itemType is 'D')"
+				},
+				"reportCode": {
+					"type": "string",
+					"description": "Report code (when itemType is 'R')"
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order"
+				},
+				"label": {
+					"type": "string",
+					"description": "Menu item display text"
+				},
+				"description": {
+					"type": "string",
+					"description": "Optional description text (tooltip, subtitle)"
+				},
+				"icon": {
+					"type": "string",
+					"description": "Bootstrap icon name"
+				},
+				"children": {
+					"type": "object",
+					"description": "Child menu items (for folder/section items)",
+					"additionalProperties": {
+						"$ref": "#/$defs/menuItem"
+					}
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/schemas/print_templates.schema.json

@@ -0,0 +1,82 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Print Templates",
+	"description": "Print template declarations for a dForge module package (ui/print_templates.json). Each key is the template_cd; the value declares either a printable template (default) or a reusable snippet pulled into other templates via {% include 'module_cd.snippet_cd' %}.",
+	"type": "object",
+	"additionalProperties": {
+		"type": "object",
+		"properties": {
+			"type": {
+				"type": "string",
+				"enum": ["template", "snippet"],
+				"default": "template",
+				"description": "'template' (default) — a full printable form bound to an entity. 'snippet' — a reusable Liquid partial, module-scoped, no entity binding, included from other templates."
+			},
+			"entityCd": {
+				"type": "string",
+				"description": "Entity code this template renders. Required when type='template'; ignored when type='snippet'. Cross-module form 'module.entity' is supported (e.g. fin-ch ships a template for fin.invoice)."
+			},
+			"description": {
+				"type": "string",
+				"description": "Human-readable label shown in the print menu."
+			},
+			"template": {
+				"type": "string",
+				"description": "Inline Liquid HTML. Either 'template' or 'file' must be set; 'file' takes precedence when both are present."
+			},
+			"file": {
+				"type": "string",
+				"description": "Relative path under the module's print_templates/ directory (e.g. 'invoice.html'). Loaded at install time."
+			},
+			"css": {
+				"type": "string",
+				"description": "Inline CSS, or a filename ending in .css (resolved relative to print_templates/). Snippets typically inherit CSS from the host template and omit this."
+			},
+			"pageSettings": {
+				"type": "object",
+				"description": "Default page geometry applied when the user prints from the UI. Stored as jsonb on the row; the editor lets users tweak per-template.",
+				"properties": {
+					"size": {
+						"type": "string",
+						"enum": ["A4", "letter", "legal"],
+						"default": "A4"
+					},
+					"orientation": {
+						"type": "string",
+						"enum": ["portrait", "landscape"],
+						"default": "portrait"
+					},
+					"margins": {
+						"type": "object",
+						"properties": {
+							"top":    { "type": "string", "description": "CSS length, e.g. '15mm'." },
+							"right":  { "type": "string" },
+							"bottom": { "type": "string" },
+							"left":   { "type": "string" }
+						},
+						"additionalProperties": false
+					}
+				},
+				"additionalProperties": false
+			}
+		},
+		"additionalProperties": false,
+		"allOf": [
+			{
+				"if": { "properties": { "type": { "const": "snippet" } }, "required": ["type"] },
+				"then": {
+					"description": "Snippets must not declare entityCd and their template_cd must not contain '.' (collides with {% include 'module_cd.snippet_cd' %})."
+				},
+				"else": {
+					"required": ["entityCd"]
+				}
+			},
+			{
+				"anyOf": [
+					{ "required": ["file"] },
+					{ "required": ["template"] }
+				]
+			}
+		]
+	}
+}

package/schemas/reports.schema.json

@@ -0,0 +1,225 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/reports.schema.json",
+	"title": "dForge Module Reports",
+	"description": "Report definitions for a dForge module: a map of report code → report definition. Reports are not listed in manifest.json; the install pipeline picks up ui/reports.json automatically.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/report"
+	},
+	"$defs": {
+		"report": {
+			"type": "object",
+			"required": ["description", "layout", "datasets"],
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Human-readable report title"
+				},
+				"layout": {
+					"$ref": "#/$defs/layout"
+				},
+				"datasets": {
+					"type": "object",
+					"description": "Map of dataset code → dataset definition. Panels reference datasets by code via `datasetCd`.",
+					"additionalProperties": { "$ref": "#/$defs/dataset" }
+				},
+				"parameters": {
+					"type": "object",
+					"description": "Report-level parameters (alternative to per-dataset `params`). Map of param code → param definition.",
+					"additionalProperties": { "$ref": "#/$defs/paramDef" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"layout": {
+			"type": "object",
+			"required": ["panels"],
+			"properties": {
+				"panels": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/panel" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"panel": {
+			"type": "object",
+			"required": ["vizType", "datasetCd"],
+			"properties": {
+				"vizType": {
+					"type": "string",
+					"enum": ["table", "chart", "metric", "pivot"],
+					"description": "Visualization type"
+				},
+				"datasetCd": {
+					"type": "string",
+					"description": "Dataset code (key in the parent `datasets` map)"
+				},
+				"title": { "type": "string" },
+				"config": {
+					"type": "object",
+					"description": "Viz-type-specific configuration. For chart: { chartType, categoryCol, valueCol, agg, chartSize }. For table: { groupRules, aggregations }."
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"dataset": {
+			"type": "object",
+			"required": ["datasetType"],
+			"properties": {
+				"caption": {
+					"type": "string",
+					"description": "Display label for the dataset (used in panel headings if no `title`)"
+				},
+				"datasetType": {
+					"type": "string",
+					"enum": ["Q", "S"],
+					"description": "Q = SQL/entity query, S = stored procedure"
+				},
+				"query": {
+					"$ref": "#/$defs/query",
+					"description": "Used when datasetType is 'Q'"
+				},
+				"procedureName": {
+					"type": "string",
+					"description": "Used when datasetType is 'S'"
+				},
+				"columnsDef": {
+					"type": "object",
+					"description": "Optional column metadata overrides: field code → { label, visible, ... }",
+					"additionalProperties": { "$ref": "#/$defs/columnDef" }
+				},
+				"params": {
+					"type": "object",
+					"description": "Dataset-level parameters (alternative to top-level `parameters`)",
+					"additionalProperties": { "$ref": "#/$defs/paramDef" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"query": {
+			"type": "object",
+			"required": ["entityCd"],
+			"properties": {
+				"entityCd": {
+					"type": "string",
+					"description": "Source entity code"
+				},
+				"columns": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Column codes to select (supports dot navigation: 'customer.name')"
+				},
+				"filter": {
+					"$ref": "#/$defs/filter"
+				},
+				"sort": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/sortClause" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"sortClause": {
+			"type": "object",
+			"required": ["c"],
+			"properties": {
+				"c": { "type": "string", "description": "Column code" },
+				"d": {
+					"type": "string",
+					"enum": ["asc", "desc"],
+					"description": "Sort direction (default: asc)"
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"columnDef": {
+			"type": "object",
+			"properties": {
+				"label": { "type": "string" },
+				"visible": { "type": "boolean" },
+				"width": { "type": "integer", "minimum": 1 }
+			},
+			"additionalProperties": false
+		},
+
+		"paramDef": {
+			"type": "object",
+			"required": ["fieldTypeCd"],
+			"properties": {
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Field type code (see settings.schema.json for the common list)"
+				},
+				"label": { "type": "string" },
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order of the parameter in the report's parameter form. Read by ReportRegistrar (paramDef.OrderNum); falls back to declaration order when omitted."
+				},
+				"required": {
+					"type": "boolean",
+					"default": false,
+					"description": "Whether the user must provide a value (older modules also use `isRequired`)"
+				},
+				"isRequired": {
+					"type": "boolean",
+					"description": "Alternate spelling of `required` used by some modules. Prefer `required` for new code."
+				},
+				"default": {
+					"description": "Default value applied if the user doesn't provide one"
+				},
+				"link": {
+					"type": "object",
+					"description": "Entity link for lookup-type params (alternative to nesting under `params.link`). Shape: { entity: '<code>', otherKey?: '<column>' }.",
+					"properties": {
+						"entity": { "type": "string" },
+						"otherKey": { "type": "string" }
+					},
+					"additionalProperties": false
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type-specific params (e.g. lookup → { link: { entity, otherKey } })"
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"filter": {
+			"description": "Canonical dForge filter expression — same shape as data_views.json filter. Either `{c, o, v}` or `{g, i: [...]}`.",
+			"oneOf": [
+				{ "$ref": "#/$defs/filterCondition" },
+				{ "$ref": "#/$defs/filterGroup" }
+			]
+		},
+		"filterCondition": {
+			"type": "object",
+			"required": ["c", "o"],
+			"properties": {
+				"c": { "type": "string" },
+				"o": { "type": "string" },
+				"v": {}
+			},
+			"additionalProperties": false
+		},
+		"filterGroup": {
+			"type": "object",
+			"required": ["g", "i"],
+			"properties": {
+				"g": { "type": "string", "enum": ["and", "or"] },
+				"i": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/filter" }
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/schemas/roles.schema.json

@@ -0,0 +1,32 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/roles.schema.json",
+	"title": "dForge Roles",
+	"description": "Role definitions with entity rights for a dForge module",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/role"
+	},
+	"$defs": {
+		"role": {
+			"type": "object",
+			"required": ["description", "rights"],
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Role display name"
+				},
+				"rights": {
+					"type": "object",
+					"description": "Entity rights: entity code → rights string",
+					"additionalProperties": {
+						"type": "string",
+						"pattern": "^[SIUDCE]*$",
+						"description": "Rights: S=Select, I=Insert, U=Update, D=Delete, C=Clone, E=Execute"
+					}
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/schemas/seed_data.schema.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/seed_data.schema.json",
+	"title": "dForge Seed Data",
+	"description": "Seed data records for a dForge entity",
+	"type": "object",
+	"required": ["entityCode", "records"],
+	"properties": {
+		"entityCode": {
+			"type": "string",
+			"description": "Target entity code to insert records into"
+		},
+		"records": {
+			"type": "array",
+			"description": "Array of records, each record is an object with column_code → value",
+			"items": {
+				"type": "object",
+				"additionalProperties": true
+			}
+		}
+	},
+	"additionalProperties": false
+}

package/schemas/settings.schema.json

@@ -0,0 +1,55 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/settings.schema.json",
+	"title": "dForge Module Settings",
+	"description": "Module-level settings definitions: a flat map of setting code → setting definition. Settings are folder-scoped at runtime (values inherit through the folder tree) and surface in the Module Settings UI.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/setting"
+	},
+	"$defs": {
+		"setting": {
+			"type": "object",
+			"required": ["fieldTypeCd"],
+			"properties": {
+				"fieldTypeCd": {
+					"type": "string",
+					"description": "Field type code (must match one in dforge.field_type). Common values: text, number, integer, decimal, boolean, checkbox, dropdown, multiSelect, date, dateTime, time, image, file, fileList, lookup, color, currency, percent, html, markdown, password, email, phone, url, textarea, json."
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"enum": ["string", "number", "bool", "date", "dateTime", "time", "json"],
+					"description": "Underlying primitive datatype. Older settings declare this explicitly; newer settings (using `formula`) often omit it."
+				},
+				"label": {
+					"type": "string",
+					"description": "Display label (newer style). Prefer this over `description`/`desc` for new settings."
+				},
+				"description": {
+					"type": "string",
+					"description": "Display label (older style). Use `label` for new settings."
+				},
+				"desc": {
+					"type": "string",
+					"description": "Alternative label key used by some older modules. Prefer `label`."
+				},
+				"defaultValue": {
+					"description": "Default value before the user sets one. Type matches `baseDatatypeCd`."
+				},
+				"formula": {
+					"type": "string",
+					"description": "Formula expression to evaluate the default (e.g. \"'USD'\"). Alternative to `defaultValue`."
+				},
+				"required": {
+					"type": "boolean",
+					"description": "If true, the setting must be set somewhere in the folder chain for installation to proceed."
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type-specific parameters. Examples: dropdown → { options: [...] }; number → { min, max }; lookup → { link: { entity, otherKey } }."
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}