@mat3ra/esse 2026.7.14-0 → 2026.8.13-0

package/dist/js/utils/ajv.d.ts

@@ -18,10 +18,11 @@ export declare function validate(data: AnyObject, jsonSchema: SchemaObject): {
     errors: import("ajv").ErrorObject<string, Record<string, any>, unknown>[] | null | undefined;
 };
 /**
- * Validates and clean a given example against the schema
- * @param example example to validate.
- * @param schema schema to validate the example with.
- * @returns whether example is valid.
+ * Validates and cleans data against the schema.
+ * Drops null properties first (empty strings kept for entity placeholders), then AJV removeAdditional.
+ * @param data data to validate (mutated in place).
+ * @param jsonSchema schema to validate the data with.
+ * @returns whether data is valid.
  */
 export declare function validateAndClean(data: AnyObject, jsonSchema: SchemaObject, { coerceTypes, useDefaults }?: {
     coerceTypes?: boolean | undefined;
@@ -30,4 +31,4 @@ export declare function validateAndClean(data: AnyObject, jsonSchema: SchemaObje
     isValid: boolean | Promise<any>;
     errors: import("ajv").ErrorObject<string, Record<string, any>, unknown>[] | null | undefined;
 };
-export {};
+export { removeEmptyAndNullProperties } from "./removeEmptyAndNullProperties";

package/dist/js/utils/ajv.js

@@ -3,12 +3,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeEmptyAndNullProperties = void 0;
 exports.getValidator = getValidator;
 exports.validate = validate;
 exports.validateAndClean = validateAndClean;
 const ajv_1 = __importDefault(require("ajv"));
 const ajv_formats_1 = __importDefault(require("ajv-formats"));
 const schemaUtils_1 = require("../esse/schemaUtils");
+const jsonSchemaToTypescriptKeywords_1 = __importDefault(require("./ajvKeywords/jsonSchemaToTypescriptKeywords"));
+const removeEmptyAndNullProperties_1 = require("./removeEmptyAndNullProperties");
 function addAdditionalPropertiesToSchema(schema, additionalProperties = false) {
     return (0, schemaUtils_1.mapObjectDeep)(schema, (object) => {
         const schema = object;
@@ -51,11 +54,17 @@ const ajvValidatorAndCleanerWithCoercingTypesNoDefaults = new ajv_1.default({
     coerceTypes: true,
     useDefaults: false,
 });
-(0, ajv_formats_1.default)(ajvValidator);
-(0, ajv_formats_1.default)(ajvValidatorAndCleaner);
-(0, ajv_formats_1.default)(ajvValidatorAndCleanerNoDefaults);
-(0, ajv_formats_1.default)(ajvValidatorAndCleanerWithCoercingTypes);
-(0, ajv_formats_1.default)(ajvValidatorAndCleanerWithCoercingTypesNoDefaults);
+const ajvInstances = [
+    ajvValidator,
+    ajvValidatorAndCleaner,
+    ajvValidatorAndCleanerNoDefaults,
+    ajvValidatorAndCleanerWithCoercingTypes,
+    ajvValidatorAndCleanerWithCoercingTypesNoDefaults,
+];
+ajvInstances.forEach((instance) => {
+    (0, ajv_formats_1.default)(instance);
+    (0, jsonSchemaToTypescriptKeywords_1.default)(instance);
+});
 function getAjvInstance({ clean, coerceTypes, useDefaults }) {
     if (clean && coerceTypes) {
         return useDefaults
@@ -97,12 +106,14 @@ function validate(data, jsonSchema) {
     };
 }
 /**
- * Validates and clean a given example against the schema
- * @param example example to validate.
- * @param schema schema to validate the example with.
- * @returns whether example is valid.
+ * Validates and cleans data against the schema.
+ * Drops null properties first (empty strings kept for entity placeholders), then AJV removeAdditional.
+ * @param data data to validate (mutated in place).
+ * @param jsonSchema schema to validate the data with.
+ * @returns whether data is valid.
  */
 function validateAndClean(data, jsonSchema, { coerceTypes = false, useDefaults = true } = {}) {
+    (0, removeEmptyAndNullProperties_1.removeEmptyAndNullProperties)(data);
     const validator = getValidator(jsonSchema, { clean: true, coerceTypes, useDefaults });
     const isValid = validator(data);
     return {
@@ -110,3 +121,5 @@ function validateAndClean(data, jsonSchema, { coerceTypes = false, useDefaults =
         errors: validator.errors,
     };
 }
+var removeEmptyAndNullProperties_2 = require("./removeEmptyAndNullProperties");
+Object.defineProperty(exports, "removeEmptyAndNullProperties", { enumerable: true, get: function () { return removeEmptyAndNullProperties_2.removeEmptyAndNullProperties; } });

package/dist/js/utils/ajvKeywords/jsonSchemaToTypescriptKeywords.d.ts

@@ -0,0 +1,7 @@
+import type Ajv from "ajv";
+/**
+ * Schemas include json-schema-to-typescript hints (`tsType`, `tsEnumNames`, …).
+ * Ajv strict mode rejects unknown keywords; register them as no-ops so the same schemas work for
+ * runtime validation.
+ */
+export default function addJsonSchemaToTypescriptKeywords(ajv: Ajv): void;

package/dist/js/utils/ajvKeywords/jsonSchemaToTypescriptKeywords.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = addJsonSchemaToTypescriptKeywords;
+/**
+ * Schemas include json-schema-to-typescript hints (`tsType`, `tsEnumNames`, …).
+ * Ajv strict mode rejects unknown keywords; register them as no-ops so the same schemas work for
+ * runtime validation.
+ */
+function addJsonSchemaToTypescriptKeywords(ajv) {
+    const validateNoop = () => true;
+    ajv.addKeyword({
+        keyword: "tsType",
+        validate: validateNoop,
+        errors: false,
+    });
+    ajv.addKeyword({
+        keyword: "tsEnumNames",
+        validate: validateNoop,
+        errors: false,
+    });
+}

package/dist/js/utils/removeEmptyAndNullProperties.d.ts

@@ -0,0 +1,9 @@
+export type AnyObject = Record<string, any>;
+/**
+ * Recursively removes null properties from an object.
+ * Empty strings are preserved (entity schemas use "" as intentional placeholders, e.g. flowchart links).
+ * Nested objects are cleaned in place; array elements are walked but not removed.
+ * @param obj The object to clean
+ * @returns The cleaned object (mutates the original)
+ */
+export declare function removeEmptyAndNullProperties(obj: AnyObject): AnyObject;

package/dist/js/utils/removeEmptyAndNullProperties.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeEmptyAndNullProperties = removeEmptyAndNullProperties;
+/**
+ * Recursively removes null properties from an object.
+ * Empty strings are preserved (entity schemas use "" as intentional placeholders, e.g. flowchart links).
+ * Nested objects are cleaned in place; array elements are walked but not removed.
+ * @param obj The object to clean
+ * @returns The cleaned object (mutates the original)
+ */
+function removeEmptyAndNullProperties(obj) {
+    if (typeof obj !== "object" || obj === null) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        obj.forEach((item) => removeEmptyAndNullProperties(item));
+        return obj;
+    }
+    Object.keys(obj).forEach((key) => {
+        const value = obj[key];
+        if (value === null) {
+            delete obj[key];
+        }
+        else if (typeof value === "object") {
+            removeEmptyAndNullProperties(value);
+        }
+    });
+    return obj;
+}

package/example/properties_directory/scalar/defect_formation_energy.json

@@ -0,0 +1,5 @@
+{
+    "name": "defect_formation_energy",
+    "units": "eV",
+    "value": 3.5
+}

package/manifest/properties.yaml

@@ -59,6 +59,12 @@ formation_energy:
   schemaId: properties-directory/scalar/formation-energy
   isResult: true
 
+defect_formation_energy:
+  defaults:
+    units: eV
+  schemaId: properties-directory/scalar/defect-formation-energy
+  isResult: true
+
 total_force:
   defaults:
     units: eV/angstrom

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/esse",
-    "version": "2026.7.14-0",
+    "version": "2026.8.13-0",
     "description": "Mat3ra's Excellent Source of Schemas and Examples (ESSE) for Digital Materials R&D",
     "scripts": {
         "transpile": "tsc -p tsconfig-transpile.json",

package/schema/material/material_properties.json

@@ -39,10 +39,6 @@
             "description": "File information if material was exported from POSCAR, XYZ or UPF file.",
             "$ref": "../system/file_source.json"
         },
-        "scaledHash": {
-            "description": "Hash string for a scaled structure with lattice vector a set to 1 (eg. for materials under pressure).",
-            "type": "string"
-        },
         "icsdId": {
             "description": "Corresponding ICSD id of the material",
             "type": "integer"

package/schema/material_enhanced.json

@@ -0,0 +1,18 @@
+{
+    "$id": "material-enhanced",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "material enhanced schema",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "material.json"
+        },
+        {
+            "properties": {
+                "basis": {
+                    "$ref": "properties_directory/structural/basis_constrained.json"
+                }
+            }
+        }
+    ]
+}

package/schema/material_enhanced_hashed.json

@@ -0,0 +1,14 @@
+{
+    "$id": "material-enhanced-hashed",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "material enhanced hashed schema",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "material_enhanced.json"
+        },
+        {
+            "$ref": "material_hashed.json"
+        }
+    ]
+}

package/schema/material_hashed.json

@@ -0,0 +1,22 @@
+{
+    "$id": "material-hashed",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "material hashed schema",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "material.json"
+        },
+        {
+            "$ref": "system/hashed.json"
+        },
+        {
+            "properties": {
+                "scaledHash": {
+                    "description": "Hash string for a scaled structure with lattice vector a set to 1 (eg. for materials under pressure).",
+                    "type": "string"
+                }
+            }
+        }
+    ]
+}

package/schema/properties_directory/enum_options.json

@@ -22,6 +22,7 @@
         "ScalarPropertyEnum": {
             "type": "string",
             "enum": [
+                "defect_formation_energy",
                 "fermi_energy",
                 "formation_energy",
                 "homo_energy",

package/schema/properties_directory/scalar/defect_formation_energy.json

@@ -0,0 +1,21 @@
+{
+    "$id": "properties-directory/scalar/defect-formation-energy",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Defect formation energy property schema",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "../../core/reusable/energy.json"
+        }
+    ],
+    "properties": {
+        "name": {
+            "enum": [
+                "defect_formation_energy"
+            ]
+        }
+    },
+    "required": [
+        "name"
+    ]
+}

package/schema/properties_directory/structural/basis_constrained.json

@@ -0,0 +1,19 @@
+{
+    "$id": "properties-directory/structural/basis-constrained",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "basis constrained schema",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "basis.json"
+        },
+        {
+            "properties": {
+                "constraints": {
+                    "$ref": "basis/atomic_constraints.json"
+                }
+            },
+            "required": ["constraints"]
+        }
+    ]
+}

package/schema/property/holder.json

@@ -36,6 +36,9 @@
                 {
                     "$ref": "../properties_directory/scalar/interfacial_energy.json"
                 },
+                {
+                    "$ref": "../properties_directory/scalar/defect_formation_energy.json"
+                },
                 {
                     "$ref": "../properties_directory/scalar/thermal_correction_to_energy.json"
                 },

package/schema/system/bankable.json

@@ -7,14 +7,9 @@
         "exabyteId": {
             "description": "Identity of the corresponding bank entity",
             "type": "string"
-        },
-        "hash": {
-            "description": "Hash string which is calculated based on the meaningful fields of the entity. Used to identify equal entities.",
-            "type": "string"
         }
     },
     "required": [
-        "exabyteId",
-        "hash"
+        "exabyteId"
     ]
 }

package/schema/system/hashed.json

@@ -0,0 +1,15 @@
+{
+    "$id": "system/hashed",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "hashed schema",
+    "type": "object",
+    "properties": {
+        "hash": {
+            "description": "Hash string which is calculated based on the meaningful fields of the entity. Used to identify equal entities.",
+            "type": "string"
+        }
+    },
+    "required": [
+        "hash"
+    ]
+}

package/schema/system/status.json

@@ -3,30 +3,14 @@
     "$schema": "http://json-schema.org/draft-07/schema#",
     "title": "status schema",
     "type": "object",
+    "allOf": [
+        {
+            "$ref": "status_track.json"
+        }
+    ],
     "properties": {
         "status": {
             "type": "string"
-        },
-        "statusTrack": {
-            "type": "array",
-            "items": {
-                "type": "object",
-                "properties": {
-                    "trackedAt": {
-                        "type": "number"
-                    },
-                    "status": {
-                        "type": "string"
-                    },
-                    "repetition": {
-                        "type": "number"
-                    }
-                },
-                "required": [
-                    "trackedAt",
-                    "status"
-                ]
-            }
         }
     }
 }

package/schema/system/status_track.json

@@ -0,0 +1,29 @@
+{
+    "$id": "system/status-track",
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "status track schema",
+    "type": "object",
+    "properties": {
+        "statusTrack": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "trackedAt": {
+                        "type": "number"
+                    },
+                    "status": {
+                        "type": "string"
+                    },
+                    "repetition": {
+                        "type": "number"
+                    }
+                },
+                "required": [
+                    "trackedAt",
+                    "status"
+                ]
+            }
+        }
+    }
+}

package/schema/workflow/unit/base.json

@@ -14,7 +14,7 @@
             "$ref": "../../system/tags.json"
         },
         {
-            "$ref": "../../system/status.json"
+            "$ref": "../../system/status_track.json"
         },
         {
             "$ref": "./mixins/base.json"

package/schema/workflow/unit/mixins/base.json

@@ -7,25 +7,6 @@
         "isDraft": {
             "type": "boolean"
         },
-        "type": {
-            "description": "type of the unit",
-            "type": "string"
-        },
-        "name": {
-            "description": "name of the unit. e.g. pw_scf",
-            "type": "string"
-        },
-        "status": {
-            "description": "Status of the unit.",
-            "type": "string",
-            "enum": [
-                "idle",
-                "active",
-                "warning",
-                "error",
-                "finished"
-            ]
-        },
         "head": {
             "description": "Whether this unit is the first one to be executed.",
             "type": "boolean"
@@ -41,10 +22,20 @@
         "enableRender": {
             "description": "Whether Rupy should attempt to use Jinja templating to add context variables into the unit",
             "type": "boolean"
+        },
+        "status": {
+            "description": "Status of the unit.",
+            "type": "string",
+            "enum": [
+                "idle",
+                "active",
+                "warning",
+                "error",
+                "finished"
+            ]
         }
     },
     "required": [
-        "type",
         "flowchartId"
     ]
 }

package/src/js/esse/JSONSchemasInterface.ts

@@ -19,6 +19,17 @@ export default class JSONSchemasInterface {
         return this.schemasCache.get(schemaId);
     }
 
+    /**
+     * Like {@link getSchemaById}, but throws if the schema is not registered.
+     */
+    static getRequiredSchemaById(schemaId: string): JSONSchema {
+        const schema = this.getSchemaById(schemaId);
+        if (!schema) {
+            throw new Error(`ESSE schema not found: ${schemaId}`);
+        }
+        return schema;
+    }
+
     /**
      * @example <caption>Search by $id regex</caption>
      * JSONSchemasInterface.matchSchema({

package/src/js/utils/ajv.ts

@@ -5,6 +5,8 @@ import addFormats from "ajv-formats";
 import { mapObjectDeep } from "../esse/schemaUtils";
 import { AnyObject } from "../esse/types";
 import type { JSONSchema } from "../esse/utils";
+import addJsonSchemaToTypescriptKeywords from "./ajvKeywords/jsonSchemaToTypescriptKeywords";
+import { removeEmptyAndNullProperties } from "./removeEmptyAndNullProperties";
 
 function addAdditionalPropertiesToSchema(schema: JSONSchema, additionalProperties = false) {
     return mapObjectDeep(schema, (object) => {
@@ -54,11 +56,18 @@ const ajvValidatorAndCleanerWithCoercingTypesNoDefaults = new Ajv({
     useDefaults: false,
 });
 
-addFormats(ajvValidator);
-addFormats(ajvValidatorAndCleaner);
-addFormats(ajvValidatorAndCleanerNoDefaults);
-addFormats(ajvValidatorAndCleanerWithCoercingTypes);
-addFormats(ajvValidatorAndCleanerWithCoercingTypesNoDefaults);
+const ajvInstances = [
+    ajvValidator,
+    ajvValidatorAndCleaner,
+    ajvValidatorAndCleanerNoDefaults,
+    ajvValidatorAndCleanerWithCoercingTypes,
+    ajvValidatorAndCleanerWithCoercingTypesNoDefaults,
+];
+
+ajvInstances.forEach((instance) => {
+    addFormats(instance);
+    addJsonSchemaToTypescriptKeywords(instance);
+});
 
 interface AjvInstanceOptions {
     clean: boolean;
@@ -123,16 +132,18 @@ export function validate(data: AnyObject, jsonSchema: SchemaObject) {
 }
 
 /**
- * Validates and clean a given example against the schema
- * @param example example to validate.
- * @param schema schema to validate the example with.
- * @returns whether example is valid.
+ * Validates and cleans data against the schema.
+ * Drops null properties first (empty strings kept for entity placeholders), then AJV removeAdditional.
+ * @param data data to validate (mutated in place).
+ * @param jsonSchema schema to validate the data with.
+ * @returns whether data is valid.
  */
 export function validateAndClean(
     data: AnyObject,
     jsonSchema: SchemaObject,
     { coerceTypes = false, useDefaults = true } = {},
 ) {
+    removeEmptyAndNullProperties(data);
     const validator = getValidator(jsonSchema, { clean: true, coerceTypes, useDefaults });
     const isValid = validator(data);
 
@@ -141,3 +152,5 @@ export function validateAndClean(
         errors: validator.errors,
     };
 }
+
+export { removeEmptyAndNullProperties } from "./removeEmptyAndNullProperties";

package/src/js/utils/ajvKeywords/jsonSchemaToTypescriptKeywords.ts

@@ -0,0 +1,22 @@
+import type Ajv from "ajv";
+
+/**
+ * Schemas include json-schema-to-typescript hints (`tsType`, `tsEnumNames`, …).
+ * Ajv strict mode rejects unknown keywords; register them as no-ops so the same schemas work for
+ * runtime validation.
+ */
+export default function addJsonSchemaToTypescriptKeywords(ajv: Ajv): void {
+    const validateNoop = (): boolean => true;
+
+    ajv.addKeyword({
+        keyword: "tsType",
+        validate: validateNoop,
+        errors: false,
+    });
+
+    ajv.addKeyword({
+        keyword: "tsEnumNames",
+        validate: validateNoop,
+        errors: false,
+    });
+}

package/src/js/utils/removeEmptyAndNullProperties.ts

@@ -0,0 +1,32 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyObject = Record<string, any>;
+
+/**
+ * Recursively removes null properties from an object.
+ * Empty strings are preserved (entity schemas use "" as intentional placeholders, e.g. flowchart links).
+ * Nested objects are cleaned in place; array elements are walked but not removed.
+ * @param obj The object to clean
+ * @returns The cleaned object (mutates the original)
+ */
+export function removeEmptyAndNullProperties(obj: AnyObject): AnyObject {
+    if (typeof obj !== "object" || obj === null) {
+        return obj;
+    }
+
+    if (Array.isArray(obj)) {
+        obj.forEach((item) => removeEmptyAndNullProperties(item));
+        return obj;
+    }
+
+    Object.keys(obj).forEach((key) => {
+        const value = obj[key];
+
+        if (value === null) {
+            delete obj[key];
+        } else if (typeof value === "object") {
+            removeEmptyAndNullProperties(value);
+        }
+    });
+
+    return obj;
+}