@dforge-core/metadata 0.0.1 → 0.0.3

package/schemas/entity.schema.json

@@ -0,0 +1,450 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/entity.schema.json",
+	"title": "dForge Entity Definition",
+	"description": "Defines an entity (table/view mapping) for a dForge module",
+	"type": "object",
+	"required": ["fields"],
+	"properties": {
+		"extends": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$",
+			"description": "Qualified entity code of the target entity to extend (e.g. 'fin.invoice'). When set, this entity definition adds columns to an existing entity owned by another module instead of creating a new entity. Physical columns are stored in a 1:1 extension table."
+		},
+		"description": {
+			"type": "string",
+			"description": "Human-readable description of the entity"
+		},
+		"schema": {
+			"type": "string",
+			"description": "Database schema name override (defaults to module schema)"
+		},
+		"dbObject": {
+			"type": "string",
+			"description": "Database table or view name (defaults to entity code)"
+		},
+		"isView": {
+			"type": "boolean",
+			"description": "When true, entity maps to a SQL view (read-only, no DDL generation). Default: false (table-backed).",
+			"default": false
+		},
+		"viewSql": {
+			"type": "string",
+			"description": "SQL SELECT statement for view-backed entities (isView=true). Executed as CREATE OR REPLACE VIEW during module install."
+		},
+		"toString": {
+			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\". Optional in extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
+		},
+		"traits": {
+			"type": "array",
+			"description": "Entity traits expanded during module install (authoring shortcut). Trait definitions loaded from DB (seeded by metadata module).",
+			"items": {
+				"type": "string",
+				"enum": ["identity", "audit", "audit-full", "soft-delete", "sorting", "postable", "accumulation", "ledger", "period", "file-library"]
+			},
+			"uniqueItems": true
+		},
+		"fields": {
+			"type": "object",
+			"description": "Column definitions keyed by column code. Column codes must start with a letter or underscore and contain only letters, digits, and underscores — a leading `-` is reserved for the sort descending prefix in `view_json.order`.",
+			"propertyNames": {
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+			},
+			"additionalProperties": {
+				"$ref": "#/$defs/field"
+			}
+		},
+		"constraints": {
+			"type": "object",
+			"description": "Database constraints (unique, check, etc.)"
+		},
+		"references": {
+			"type": "object",
+			"description": "Foreign key reference definitions (legacy format, prefer 'link' on field)",
+			"additionalProperties": {
+				"$ref": "#/$defs/entityReference"
+			}
+		},
+		"indexes": {
+			"type": "object",
+			"description": "Database index definitions"
+		},
+		"numberSequence": {
+			"$ref": "#/$defs/numberSequence",
+			"description": "Automatic document numbering configuration for this entity"
+		},
+		"period": {
+			"$ref": "#/$defs/periodConfig",
+			"description": "Period entity configuration. Requires 'period' trait."
+		},
+		"accumulation": {
+			"$ref": "#/$defs/accumulationConfig",
+			"description": "Accumulation registry configuration (simple document without lines). Requires 'accumulation' trait."
+		},
+		"params": {
+			"type": "object",
+			"description": "Entity-level parameters for platform behavior flags",
+			"properties": {
+				"restricted": {
+					"type": "boolean",
+					"description": "When true, blocks generic data.get/data.set access. Entity must be accessed via dedicated API methods.",
+					"default": false
+				}
+			},
+			"additionalProperties": true
+		}
+	},
+	"additionalProperties": false,
+	"$defs": {
+		"field": {
+			"type": "object",
+			"description": "Entity column/field definition",
+			"properties": {
+				"dbDatatype": {
+					"type": "string",
+					"description": "PostgreSQL data type (e.g. uuid, varchar, int4, bool, text, json, numeric, date, timestamp, timestamptz, bpchar)"
+				},
+				"baseDatatypeCd": {
+					"type": "string",
+					"enum": ["binary", "bool", "cuid", "culture", "date", "guid", "link", "number", "project", "string", "time", "timestamp", "xml", "json"],
+					"description": "Base data type code from field_type table (e.g. string, number, boolean, date, time, timestamp, json, binary)"
+				},
+				"columnType": {
+					"type": "string",
+					"enum": ["D", "R", "S", "F", "A", "L", "G"],
+					"description": "Column type: D=Data (physical column), R=Reference (N:1 lookup), S=Set (1:N collection), F=Formula (virtual calculated), G=Generated/Computed (physical, auto-maintained), A=Accumulation registry, L=Ledger registry"
+				},
+				"fieldTypeCd": {
+					"type": "string",
+					"enum": [
+						"text", "email", "phone", "url", "textarea", "number", "currency", "percent",
+						"checkbox", "date", "datetime", "time",
+						"dropdown", "flags", "tags", "json", "hidden", "color", "image", "file",
+						"richtext", "lookup", "user", "grid", "entitylink", "code"
+					],
+					"description": "UI field type code from field_type table"
+				},
+				"flags": {
+					"type": "string",
+					"pattern": "^[VIEMH]*$",
+					"description": "Display flags: V=Visible, I=Identity, E=Editable, M=Mandatory, H=Hidden"
+				},
+				"isPk": {
+					"type": "boolean",
+					"description": "Whether this column is part of the primary key"
+				},
+				"isNullable": {
+					"type": "boolean",
+					"description": "Whether the column allows NULL values"
+				},
+				"isIdentity": {
+					"type": "boolean",
+					"description": "Whether the column value is auto-generated (e.g. CUID primary key). Identity columns are not editable and excluded from required validation."
+				},
+				"formula": {
+					"type": "string",
+					"description": "Formula expression (for columnType 'F' or default values)"
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Display order number"
+				},
+				"description": {
+					"type": "string",
+					"description": "Human-readable column description"
+				},
+				"maxLen": {
+					"type": "integer",
+					"description": "Maximum length for varchar/text columns"
+				},
+				"precision": {
+					"type": "integer",
+					"description": "Numeric precision for decimal/currency columns"
+				},
+				"editMask": {
+					"type": "string",
+					"description": "Input mask pattern for editing"
+				},
+				"displayFmt": {
+					"type": "string",
+					"description": "Display format pattern"
+				},
+				"params": {
+					"type": "object",
+					"description": "Field-type-specific configuration (e.g. dropdown options, currency settings)",
+					"properties": {
+						"options": {
+							"type": "array",
+							"items": {
+								"oneOf": [
+									{ "type": "string" },
+									{
+										"type": "object",
+										"required": ["value", "label"],
+										"properties": {
+											"value": { "type": "string" },
+											"label": { "type": "string" },
+											"icon": { "type": "string" },
+											"color": { "type": "string" }
+										},
+										"additionalProperties": false
+									}
+								]
+							},
+							"description": "Options for dropdown/flags field types"
+						}
+					}
+				},
+				"link": {
+					"$ref": "#/$defs/fieldLink",
+					"description": "Relationship link for Reference (R) and Set (S) columns"
+				},
+				"cyclic": {
+					"type": "boolean",
+					"description": "On a self-referencing reference column (R column whose link.entity is the owning entity), set true to ALLOW parent/child cycles. When absent the self-reference is treated as an acyclic hierarchy and DB-level guards reject loops. Ignored on non-self-referencing columns."
+				},
+				"refFilter": {
+					"description": "Filter criteria for reference lookups"
+				}
+			},
+			"oneOf": [
+				{
+					"title": "Data column",
+					"description": "Physical DB column (columnType 'D' or unspecified). Requires 'dbDatatype'. Must NOT have 'link'.",
+					"required": ["dbDatatype"],
+					"properties": {
+						"columnType": { "enum": ["D"] },
+						"link": false
+					}
+				},
+				{
+					"title": "Inferred-type column",
+					"description": "Physical column where dbDatatype is inferred from fieldTypeCd (e.g. user, color)",
+					"required": ["fieldTypeCd"],
+					"properties": {
+						"columnType": { "enum": ["D"] },
+						"link": false,
+						"dbDatatype": false
+					}
+				},
+				{
+					"title": "Reference column (R)",
+					"description": "N:1 lookup (columnType 'R'). Requires 'link' and 'fieldTypeCd'. Must NOT have 'dbDatatype'.",
+					"required": ["columnType", "fieldTypeCd", "link"],
+					"properties": {
+						"columnType": { "const": "R" },
+						"dbDatatype": false
+					}
+				},
+				{
+					"title": "Set column (S)",
+					"description": "1:N collection (columnType 'S'). Requires 'link' and 'fieldTypeCd'. Must NOT have 'dbDatatype'.",
+					"required": ["columnType", "fieldTypeCd", "link"],
+					"properties": {
+						"columnType": { "const": "S" },
+						"dbDatatype": false
+					}
+				},
+				{
+					"title": "Formula column (F)",
+					"description": "Calculated virtual column (columnType 'F'). Requires 'formula'. Must NOT have 'link' or 'dbDatatype'.",
+					"required": ["columnType", "formula", "baseDatatypeCd"],
+					"properties": {
+						"columnType": { "const": "F" },
+						"link": false,
+						"baseDatatypeCd": true,
+						"dbDatatype": false
+					}
+				},
+				{
+					"title": "Accumulation registry column (A)",
+					"description": "Accumulation registry state (bool) + config. Physical column storing posted state. Config in params defines balance entity, dimensions, resources.",
+					"required": ["columnType", "dbDatatype", "params"],
+					"properties": {
+						"columnType": { "const": "A" },
+						"dbDatatype": { "const": "bool" },
+						"link": false
+					}
+				},
+				{
+					"title": "Ledger registry column (L)",
+					"description": "Ledger registry state (bool) + config. Physical column storing posted state. Config in params defines lines, movement entity, balance entity.",
+					"required": ["columnType", "dbDatatype", "params"],
+					"properties": {
+						"columnType": { "const": "L" },
+						"dbDatatype": { "const": "bool" },
+						"link": false
+					}
+				},
+				{
+					"title": "Generated/Computed column (G)",
+					"description": "Physical column auto-computed by DB trigger (aggregate over child set) or PostgreSQL GENERATED ALWAYS AS (same-row expression). Requires 'dbDatatype' and 'formula'. Formula syntax: SUM([setCol].[childField]) for aggregates, or plain SQL expression for same-row generated columns.",
+					"required": ["columnType", "dbDatatype", "formula"],
+					"properties": {
+						"columnType": { "const": "G" },
+						"link": false
+					}
+				}
+			],
+			"required": ["orderNum", "description"],
+			"additionalProperties": false
+		},
+		"fieldLink": {
+			"type": "object",
+			"description": "Relationship definition for Reference and Set columns",
+			"required": ["entity", "thisKey", "otherKey"],
+			"properties": {
+				"entity": {
+					"type": "string",
+					"description": "Target entity code (the entity being referenced or collected)"
+				},
+				"thisKey": {
+					"type": "string",
+					"description": "Column(s) in this entity (comma-separated for compound keys)"
+				},
+				"otherKey": {
+					"type": "string",
+					"description": "Column(s) in the target entity (comma-separated for compound keys)"
+				}
+			},
+			"additionalProperties": false
+		},
+		"numberSequence": {
+			"type": "object",
+			"description": "Automatic document numbering. Auto-generates a formatted number on INSERT when the target column is empty.",
+			"required": ["column", "defaultPrefix"],
+			"properties": {
+				"column": {
+					"type": "string",
+					"description": "Column code that receives the auto-generated number"
+				},
+				"prefixSettingCd": {
+					"type": "string",
+					"description": "Module setting code to resolve the prefix from (folder-scoped inheritance)"
+				},
+				"defaultPrefix": {
+					"type": "string",
+					"description": "Fallback prefix when no setting is configured"
+				},
+				"pattern": {
+					"type": "string",
+					"description": "Number format pattern. Placeholders: {prefix}, {yyyy}, {yy}, {mm}, {dd}, {seq:N}",
+					"default": "{prefix}{yyyy}-{seq:3}"
+				},
+				"resetPeriod": {
+					"type": "string",
+					"enum": ["year", "month", "day", "never"],
+					"description": "Counter reset period",
+					"default": "year"
+				}
+			},
+			"additionalProperties": false
+		},
+		"periodConfig": {
+			"type": "object",
+			"description": "Configuration for entities with the 'period' trait. Defines how date values map to period keys.",
+			"required": ["keyFormat"],
+			"properties": {
+				"keyFormat": {
+					"type": "string",
+					"description": "Format string for deriving period key from a date. Placeholders: {yyyy}, {yy}, {MM}, {dd}, {q} (quarter 1-4).",
+					"examples": ["{yyyy}-{MM}", "{yyyy}-Q{q}", "FY{yyyy}"]
+				}
+			},
+			"additionalProperties": false
+		},
+		"accumulationConfig": {
+			"type": "object",
+			"description": "Configuration for simple accumulation (document without lines, e.g. receipt → stock).",
+			"required": ["balanceEntity", "dimensions", "resources"],
+			"properties": {
+				"balanceEntity": { "type": "string", "description": "Balance entity code (e.g. 'stock')" },
+				"dimensions": {
+					"description": "Balance row lookup dimensions. Array of field names (same name on both entities) or object mapping balance_field → document_field.",
+					"oneOf": [
+						{ "type": "array", "items": { "type": "string" } },
+						{ "type": "object", "additionalProperties": { "type": "string" } }
+					]
+				},
+				"resources": {
+					"type": "object",
+					"description": "Document field → balance field resource mappings",
+					"additionalProperties": {
+						"type": "object",
+						"required": ["balanceField"],
+						"properties": {
+							"balanceField": { "type": "string" }
+						}
+					}
+				},
+				"direction": { "type": "string", "enum": ["increase", "decrease"], "description": "Fixed direction for all postings" },
+				"sign": { "$ref": "#/$defs/signConfig", "description": "Dynamic sign based on a field value (alternative to direction)" },
+				"autoCreateBalance": { "type": "boolean", "default": true },
+				"allowNegative": { "type": "boolean", "default": true },
+				"lockedFields": { "type": "array", "items": { "type": "string" }, "description": "Document fields locked when posted" }
+			},
+			"additionalProperties": false
+		},
+		"signConfig": {
+			"type": "object",
+			"description": "Dynamic sign determination based on a field value",
+			"required": ["field", "positive", "negative"],
+			"properties": {
+				"field": { "type": "string", "description": "Field code that determines direction" },
+				"positive": { "type": "array", "items": { "type": "string" }, "description": "Values that mean increase" },
+				"negative": { "type": "array", "items": { "type": "string" }, "description": "Values that mean decrease" }
+			},
+			"additionalProperties": false
+		},
+		"ledgerRegistryEntry": {
+			"type": "object",
+			"description": "Single registry target within an L-column's registries array",
+			"required": ["movementEntity", "movementMapping", "balanceEntity", "balanceMapping"],
+			"properties": {
+				"movementEntity": { "type": "string", "description": "Movement entity code (e.g. 'posting_record')" },
+				"movementMapping": {
+					"type": "object",
+					"description": "Line field → movement field mapping",
+					"additionalProperties": { "type": "string" }
+				},
+				"balanceEntity": { "type": "string", "description": "Balance entity code (e.g. 'balance_register')" },
+				"balanceMapping": {
+					"type": "object",
+					"required": ["dimensions", "debitResource", "creditResource"],
+					"properties": {
+						"dimensions": { "type": "array", "items": { "type": "string" }, "description": "Balance row dimension columns" },
+						"debitResource": { "type": "string", "description": "Balance column for debit turnover" },
+						"creditResource": { "type": "string", "description": "Balance column for credit turnover" }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		},
+		"entityReference": {
+			"type": "object",
+			"description": "Foreign key reference definition (legacy format)",
+			"required": ["from", "to"],
+			"properties": {
+				"from": {
+					"type": "object",
+					"required": ["field"],
+					"properties": {
+						"field": { "type": "string" }
+					},
+					"additionalProperties": false
+				},
+				"to": {
+					"type": "object",
+					"required": ["entity", "field"],
+					"properties": {
+						"entity": { "type": "string" },
+						"field": { "type": "string" }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/schemas/folders.schema.json

@@ -0,0 +1,108 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/folders.schema.json",
+	"title": "dForge Folders",
+	"description": "Folder tree for a dForge module. The file IS the root folder (not a map keyed by code). Sub-folders live under `children`, keyed by folder code.",
+	"$ref": "#/$defs/folder",
+	"$defs": {
+		"folder": {
+			"type": "object",
+			"properties": {
+				"label": {
+					"type": "string",
+					"description": "Folder display name"
+				},
+				"description": {
+					"type": "string",
+					"description": "Optional description text (shown in breadcrumb / header area)"
+				},
+				"parentCode": {
+					"type": ["string", "null"],
+					"description": "Parent folder code. Usually omitted: nested folders go under `children` of their parent. Only used by sparse-tree imports."
+				},
+				"folderPath": {
+					"type": "string",
+					"description": "URL-friendly folder path override"
+				},
+				"color": {
+					"type": "string",
+					"description": "Folder accent color (hex, e.g. '#2196F3')"
+				},
+				"icon": {
+					"type": "string",
+					"description": "Bootstrap icon class (e.g. 'bi-folder')"
+				},
+				"inheritSecurity": {
+					"type": "boolean",
+					"description": "Whether to inherit security rights from the parent folder. Default: true."
+				},
+				"entities": {
+					"type": "object",
+					"description": "Entity code → folder-entity binding (which view to show, quick-add, row-level filter).",
+					"additionalProperties": {
+						"$ref": "#/$defs/folderEntity"
+					}
+				},
+				"children": {
+					"type": "object",
+					"description": "Nested folders keyed by sub-folder code. Recursive — children can have their own children.",
+					"additionalProperties": {
+						"$ref": "#/$defs/folder"
+					}
+				}
+			},
+			"additionalProperties": false
+		},
+		"folderEntity": {
+			"type": "object",
+			"properties": {
+				"viewName": {
+					"type": "string",
+					"description": "Entity view name (data view code) to use in this folder. Common values include 'default'."
+				},
+				"quickAdd": {
+					"type": "boolean",
+					"description": "Enable the quick-add (+) button for this entity in this folder"
+				},
+				"rowFilter": {
+					"description": "Row-level filter. Either a SQL expression string (e.g. \"is_customer = true\") or a canonical filter object (`{c,o,v}` for one condition, `{g,i:[]}` for a group).",
+					"oneOf": [
+						{ "type": "string" },
+						{ "$ref": "#/$defs/filter" }
+					]
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"filter": {
+			"description": "Canonical dForge filter expression — same shape as in data_views.json. 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/jobs.schema.json

@@ -0,0 +1,83 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Scheduled Jobs",
+	"description": "Cron job declarations for a dForge module package (logic/jobs.json). The dForge.Scheduler service polls these and fires each job on its schedule.",
+	"type": "object",
+	"required": ["jobs"],
+	"properties": {
+		"jobs": {
+			"type": "array",
+			"maxItems": 50,
+			"description": "At most 50 jobs per module — guard against accidental fan-out from generated declarations.",
+			"items": {
+				"type": "object",
+				"required": ["code", "action", "schedule", "timeout"],
+				"properties": {
+					"code": {
+						"type": "string",
+						"maxLength": 100,
+						"pattern": "^[a-z][a-z0-9_]*$",
+						"description": "Unique identifier within the module."
+					},
+					"description": {
+						"type": "string",
+						"description": "Human-readable description of what the job does."
+					},
+					"action": {
+						"type": "string",
+						"description": "Action code in this module (e.g. 'generate_invoices'). The scheduler resolves it to action_implementation.impl_id at install time."
+					},
+					"schedule": {
+						"type": "string",
+						"description": "Five-field cron expression (minute granularity). Sub-minute schedules are rejected.",
+						"pattern": "^\\S+\\s+\\S+\\s+\\S+\\s+\\S+\\s+\\S+$"
+					},
+					"params": {
+						"type": "object",
+						"description": "Static parameters passed to the action as __params. Folder-scoped overrides go through module settings, not here.",
+						"additionalProperties": true
+					},
+					"timeout": {
+						"type": "integer",
+						"minimum": 1,
+						"maximum": 3600,
+						"description": "Hard timeout in seconds. Required — there is no implicit default. Must be > 300 only if class = 'long_running' (60-minute hard ceiling)."
+					},
+					"concurrency": {
+						"type": "integer",
+						"minimum": 1,
+						"maximum": 5,
+						"default": 1,
+						"description": "Max parallel runs. 1 means single-instance; the scheduler skips a new fire if a previous one is still in flight (Phase 3 enforcement)."
+					},
+					"idempotencyKey": {
+						"type": "string",
+						"description": "Template like '{job_cd}:{run.month}'. Resolved at fire time. A successful run with the same key blocks re-dispatch (Phase 3 enforcement)."
+					},
+					"class": {
+						"type": "string",
+						"enum": ["standard", "long_running"],
+						"default": "standard",
+						"description": "Routing class. 'long_running' is opt-in and required for any timeout > 300 seconds."
+					},
+					"timeZone": {
+						"type": "string",
+						"description": "IANA tz name (e.g. 'Asia/Tokyo'). Overrides the tenant default. Omit to fall back to auth.tenant.time_zone."
+					},
+					"enabled": {
+						"type": "boolean",
+						"default": true,
+						"description": "Master switch. False fully disables (no scheduler, no manual trigger)."
+					},
+					"paused": {
+						"type": "boolean",
+						"default": false,
+						"description": "Soft pause. Scheduler skips firing, but admin 'trigger now' still works."
+					}
+				},
+				"additionalProperties": false
+			}
+		}
+	},
+	"additionalProperties": false
+}