convention_builder 1.4.3 → 1.5.0

package/dist/module/index.js

@@ -8614,7 +8614,12 @@ var require_schema_utilities = __commonJS({
     __name(apiComposeTaxonomiesTransformation, "apiComposeTaxonomiesTransformation");
     function exampleImporter(filename, basePath = `${__dirname}/../../../definitions/examples/raw_examples_and_scripts/`, schemataSource = `${__dirname}/../../../input/collection`) {
       let rawData = JSON.parse(fs.readFileSync(`${basePath}/${filename}`)).map((obj) => {
-        let output = obj.entity;
+        let output = obj.entity ? obj.entity : obj;
+        if (!output) {
+          console.log(obj);
+          console.log(output);
+        }
+        ;
         if (output.attributes.relationships) {
           output.relationships = output.attributes.relationships;
           delete output.attributes.relationships;
@@ -8631,7 +8636,7 @@ var require_schema_utilities = __commonJS({
       });
       let newEntities = [];
       let entities = rawData.flatMap((entity) => {
-        let transformedData = apiComposeTaxonomiesTransformation(entity);
+        let transformedData = entity.relationships ? apiComposeTaxonomiesTransformation(entity) : { mainEntity: entity, newEntities: [] };
         return [transformedData.mainEntity, ...transformedData.newEntities];
       });
       return entities;
@@ -9052,6 +9057,20 @@ var require_schema_utilities = __commonJS({
       return output;
     }
     __name(findAllNonObjectAttributesInTree, "findAllNonObjectAttributesInTree");
+    function gitlabConventionURLTemplate({ conventionName, projectID }) {
+      return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/output/collection/conventions/${conventionName}/schema.json?job=copy_schemas`;
+    }
+    __name(gitlabConventionURLTemplate, "gitlabConventionURLTemplate");
+    function gitlabOverlayURLTemplate({ overlayName, projectID, baseEntityTypeAndbundle = "" }) {
+      return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/input/collection/${overlayName}/schema.json?job=copy_schemas`;
+    }
+    __name(gitlabOverlayURLTemplate, "gitlabOverlayURLTemplate");
+    function basicSchemaURLTemplate({ baseEntityTypeAndBundle, projectID }) {
+      let type = baseEntityTypeAndBundle.split("--")[0];
+      let bundle = baseEntityTypeAndBundle.split("--")[1];
+      return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/input/collection/${type}/${bundle}/schema.json?job=copy_schemas`;
+    }
+    __name(basicSchemaURLTemplate, "basicSchemaURLTemplate");
     exports.dig = dig;
     exports.bury = bury;
     exports.fixRelationshipDataField = fixRelationshipDataField;
@@ -9074,6 +9093,9 @@ var require_schema_utilities = __commonJS({
     exports.listAttributesAndSubAttributes = listAttributesAndSubAttributes;
     exports.findAllObjectAttributesInTree = findAllObjectAttributesInTree;
     exports.findAllNonObjectAttributesInTree = findAllNonObjectAttributesInTree;
+    exports.gitlabConventionURLTemplate = gitlabConventionURLTemplate;
+    exports.gitlabOverlayURLTemplate = gitlabOverlayURLTemplate;
+    exports.basicSchemaURLTemplate = basicSchemaURLTemplate;
   }
 });
 
@@ -9088,7 +9110,11 @@ var require_convention_builder = __commonJS({
       bury,
       listAttributesAndSubAttributes,
       findAllObjectAttributesInTree,
-      findAllNonObjectAttributesInTree
+      findAllNonObjectAttributesInTree,
+      gitlabOverlayURLTemplate,
+      gitlabConventionURLTemplate,
+      basicSchemaURLTemplate,
+      arrayToStructuredConvention
     } = require_schema_utilities();
     function getAttributes(root, convention) {
       let branches = convention.relationships.filter((rel) => rel.containerEntity == root).map((d) => d.mentionedEntity);
@@ -9103,21 +9129,23 @@ var require_convention_builder = __commonJS({
         name,
         validExamples,
         erroredExamples,
-        repoURL,
+        repoURLTemplateFunction = gitlabOverlayURLTemplate,
         storageFolder = `${__dirname}/../../../../output/collection/overlays`,
         strictEnums = true,
         overlay = false,
         originalSrcScript,
         trivial = false,
         baseSchemataFolder = `${__dirname}/../../../../input/collection`,
+        gitlabProjectId = process.env.CI_PROJECT_ID,
         requiredFields = [],
-        modifiedAttributes
+        modifiedAttributes,
+        deletedAttributes = []
       }) {
         this.name = name;
         this.typeAndBundle = typeAndBundle;
         this.validExamples = validExamples;
         this.erroredExamples = erroredExamples;
-        this.repoURL = repoURL;
+        this.repoURLTemplateFunction = repoURLTemplateFunction;
         this.schemaName = `${typeAndBundle}--${name}`;
         this.storageFolder = storageFolder;
         this.strictEnums = strictEnums;
@@ -9147,6 +9175,7 @@ var require_convention_builder = __commonJS({
         this.baseSchema = baseSchema;
         this.unmodifiedAttributes = listAttributesAndSubAttributes(this.baseSchema);
         this.modifiedAttributes = modifiedAttributes ? modifiedAttributes : /* @__PURE__ */ new Set([]);
+        this.deletedAttributes = deletedAttributes;
         if (!overlay) {
           this.overlay = {
             properties: {
@@ -9178,8 +9207,8 @@ var require_convention_builder = __commonJS({
        */
       updateSchema() {
         this.schema = {};
-        this.schema.$id = `${this.repoURL}/schemata/${this.typeAndBundle.replace("--", "/")}/schema.json`;
         Object.assign(this.schema, this.baseSchema);
+        this.schema.$id = this.repoURLTemplateFunction({ overlayName: this.name, projectID: this.gitlabProjectId, baseEntityTypeAndBundle: this.typeAndBundle });
         let allModifiedAttributes = listAttributesAndSubAttributes(this.overlay);
         this.modifiedAttributes = allModifiedAttributes;
         this.unmodifiedAttributes = listAttributesAndSubAttributes(this.baseSchema);
@@ -9188,6 +9217,7 @@ var require_convention_builder = __commonJS({
           let currentValue = dig(this.overlay.properties.attributes.properties, attr);
           bury(this.schema, `properties.attributes.properties.${attr}`, currentValue, false);
         });
+        this.deletedAttributes.forEach((deletedAttr) => delete this.schema.properties.attributes.properties[deletedAttr]);
         let originalRequiredFields = this.schema.properties.attributes.required ? this.schema.properties.attributes.required : [];
         let allRequiredSet = Array.from(/* @__PURE__ */ new Set([...originalRequiredFields, ...Array.from(this.requiredFields)]));
         this.schema.properties.attributes.required = allRequiredSet;
@@ -9290,6 +9320,15 @@ var require_convention_builder = __commonJS({
         ;
         this.setGenericSection({ attribute, section: subschema, description });
       }
+      /**
+       * Mark an attribute to be omitted from the resulting schema.
+       * @param {} attribute
+       */
+      deleteAttribute(attribute) {
+        this.deletedAttributes.push(attribute);
+        delete this.overlay.properties.attributes.properties[attribute];
+        this.updateAttributeStatus(attribute);
+      }
       /**
        * Build an AJV validator and ensure all valid examples are accepted and all error examples are rejected. Returns an array attribute for each set of examples, plus a general success attribute indicating wether all examples resulted as expected and a failedExamples array only listing entities for which there was no success (meanin unrejected error examples and rejected valid examples).
        */
@@ -9380,16 +9419,18 @@ var require_convention_builder = __commonJS({
       constructor({
         typeAndBundle,
         attributeOverlayName,
-        repoURL,
+        repoURLTemplateFunction = basicSchemaURLTemplate,
         strictEnums = true,
-        baseSchemataFolder = `${__dirname}/../../../../input/collection`
+        baseSchemataFolder = `${__dirname}/../../../../input/collection`,
+        gitlabProjectId = process.env.CI_PROJECT_ID
       }) {
         super({
           typeAndBundle,
-          repoURL,
+          repoURLTemplateFunction,
           storageFolder: baseSchemataFolder,
           baseSchemataFolder,
-          strictEnums
+          strictEnums,
+          gitlabProjectId
         });
         this.attributeOverlayName = attributeOverlayName;
       }
@@ -9417,12 +9458,13 @@ var require_convention_builder = __commonJS({
         title,
         schemaName,
         version,
-        repoURL,
+        repoURLTemplateFunction = gitlabConventionURLTemplate,
         description,
-        validExamples,
-        erroredExamples,
+        validExamples = [],
+        erroredExamples = [],
         storageFolder = `${__dirname}/../../../../output/collection`,
         baseSchemataFolder = `${__dirname}/../../../../input/collection`,
+        gitlabProjectId = process.env.CI_PROJECT_ID,
         strictEnums = false,
         overlays = false,
         relationships = false,
@@ -9437,13 +9479,14 @@ var require_convention_builder = __commonJS({
         this.description = description;
         this.schemaName = schemaName;
         this.version = version;
-        this.repoURL = repoURL, this.validExamples = validExamples;
+        this.repoURLTemplateFunction = repoURLTemplateFunction, this.validExamples = validExamples;
         this.erroredExamples = erroredExamples;
         this.overlays = {};
         this.relationships = [];
         this.required = [];
         this.storageFolder = storageFolder;
         this.baseSchemataFolder = baseSchemataFolder;
+        this.gitlabProjectId = gitlabProjectId;
         if (overlays) {
           let overlayNames = Object.keys(overlays);
           this.overlays = {};
@@ -9519,7 +9562,7 @@ var require_convention_builder = __commonJS({
         this.schema = {
           title: this.title,
           type: "object",
-          $id: `${this.repoURL}/${this.version}/conventions/${this.schemaName}`,
+          $id: this.repoURLTemplateFunction({ conventionName: this.schemaName, projectID: this.gitlabProjectId }),
           $schema: "https://json-schema.org/draft/2020-12/schema",
           properties: {},
           description: this.description,
@@ -9744,17 +9787,102 @@ import TabItem from '@theme/TabItem';
         let body = [header, mainText, "# View Schema\n", "<Tabs>", schemaPluginInvocation, schemaPluginInvocationRequiredOnly, codeBlock, conventionAsText, "</Tabs>"].join("\n");
         return body;
       }
+      getExamplesFromFile({ path }) {
+        let isFolder = fs.lstatSync(path).isDirectory();
+        let isJSONFile = new RegExp(/\.json$/i).test(path);
+        let noFilesError = `The provided path (${path}) does not lead to JSON file nor a folder containing JSON files. Folder: ${isFolder}, JSON File: ${isJSONFile}`;
+        let output = [];
+        if (isFolder) {
+          let folderExamples = fs.readdirSync(path, (error, files) => {
+            return files;
+          }).filter((path2) => new RegExp(/\.json$/i).test(path2)).map((filename) => {
+            let examples = JSON.parse(fs.readFileSync(`${path}/${filename}`));
+            return examples;
+          });
+          if (folderExamples.length == 0) {
+            throw new Error(noFilesError);
+          }
+          ;
+          output.push(...folderExamples);
+        } else if (isJSONFile) {
+          let example = JSON.parse(fs.readFileSync(path));
+          output.push(example);
+        } else {
+          throw new Error(noFilesError);
+        }
+        ;
+        return output;
+      }
+      /**
+       * Will retrieve an individual example from a JSON file or all examples in a given folder. They all need to be either valid or invalid examples, and that should be indicated by the 'is_valid_example' attribute.
+       * @param {string} path -- A string representing an absolute path, leading to either a JSON file containing an individual example or a folder containing several examples. 
+       * @param {object|array} object -- Either an array of examples or an individual example. 
+       * @param {boolean} is_valid_example -- Whether to store the provided examples as valid examples or errors, for the tests.
+       * @param {boolean} structured_as_array -- Mark as "true" if the provided example is structured as a loose array of entities, as FarmOS delivers them (instead of structured as a convention object in which every entity is a property). The method will try to structure the entity and return meaningful information if it is not successful in doing so.
+       */
+      addExample({ path, object, is_valid_example, structured_as_array }) {
+        let output = {
+          success: false,
+          errors: []
+        };
+        if (!path && !object) {
+          throw new Error(`Either an object or a path leading to a folder or a json file need to be provided. Both arguments are empty.`);
+        }
+        ;
+        let newExamples = [];
+        if (object) {
+          if (!Array.isArray(object)) {
+            newExamples.push(object);
+          } else {
+            newExamples.push(...object);
+          }
+          ;
+        } else if (path) {
+          newExamples = this.getExamplesFromFile({ path });
+        }
+        ;
+        if (structured_as_array) {
+          newExamples = newExamples.map((exampleArray) => {
+            let exampleObject = arrayToStructuredConvention({
+              entitiesArray: exampleArray,
+              conventionObject: this
+            });
+            if (!exampleObject.is_valid && is_valid_example) {
+              output.errors.push("The `arrayToStructuredConvention` function wasn't able to rebuild a valid instance of this convention's schema from the provided array of loose entities. Look into the '.structuringAttempt' attribute for more information.");
+            }
+            ;
+            if (!is_valid_example) {
+              output.warning = "Since the example is not marked as 'valid', we can't check it is being properly parsed. Please review the output 'assembled_entity' to check it looks as it should.";
+            }
+            ;
+            output.structuringAttempt = exampleObject;
+            return exampleObject.assembled_entity;
+          });
+        }
+        ;
+        if (is_valid_example) {
+          this.validExamples.push(...newExamples);
+        } else {
+          this.erroredExamples.push(...newExamples);
+        }
+        ;
+        if (output.errors.length == 0) {
+          output.success = true;
+        }
+        ;
+        return output;
+      }
       /**
        * Build an AJV validator and ensure all valid examples are accepted and all error examples are rejected. Returns an array attribute for each set of examples, plus a general success attribute indicating wether all examples resulted as expected and a failedExamples array only listing entities for which there was no success (meanin unrejected error examples and rejected valid examples).
        */
       testExamples() {
         let generalOutput = {};
         if (!this.validExamples || !this.erroredExamples) {
-          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute`);
+          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute. Valid examples amount: ${this.validExamples ? this.validExamples.length : "validExamples is not an array"}, errored examples amount: ${this.erroredExamples ? this.erroredExamples.length : "erroredExamples is not an array"}.`);
         }
         ;
         if (this.validExamples.length == 0 || this.erroredExamples.length == 0) {
-          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute`);
+          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute. Valid examples amount: ${this.validExamples ? this.validExamples.length : "validExamples is not an array"}, errored examples amount: ${this.erroredExamples ? this.erroredExamples.length : "erroredExamples is not an array"}.`);
         }
         ;
         this.updateSchema();
@@ -9860,7 +9988,7 @@ import TabItem from '@theme/TabItem';
     };
     __name(_ConventionSchema, "ConventionSchema");
     var ConventionSchema = _ConventionSchema;
-    var _AttributeOverlay = class _AttributeOverlay {
+    var _InputConventionChanges = class _InputConventionChanges {
       constructor({
         type,
         bundle,
@@ -9868,7 +9996,8 @@ import TabItem from '@theme/TabItem';
         baseSchemataFolder = `${__dirname}/../../../../input/collection`,
         sourceSchemataFile = `${__dirname}/../../../../input/farmos.json`,
         overlayName,
-        overlayDescription
+        overlayDescription,
+        gitlabProjectId = process.env.CI_PROJECT_ID
       }) {
         let integralSchemataFile = JSON.parse(fs.readFileSync(sourceSchemataFile));
         this.type = type;
@@ -9879,6 +10008,7 @@ import TabItem from '@theme/TabItem';
         this.sourceSchemata = integralSchemataFile;
         this.lexicon = [...findAllObjectAttributesInTree(this.sourceSchemata), ...findAllNonObjectAttributesInTree(this.sourceSchemata)];
         this.baseSchemataFolder = baseSchemataFolder;
+        this.gitlabProjectId = gitlabProjectId;
         let involvedSchemata = this.lexicon.filter((entry) => this.attribute == entry.attribute).flatMap((entry) => entry.instances).filter((instance) => this.type ? instance.type == this.type : true).filter((instance) => this.bundle ? instance.bundle == this.bundle : true).map((d) => d.schema);
         this.targetSchemata = Array.from(new Set(involvedSchemata));
         this.overlays = [];
@@ -9886,8 +10016,10 @@ import TabItem from '@theme/TabItem';
           let currentOverlay = new AttributePatchingSchemaOverlay({
             typeAndBundle: target,
             attributeOverlayName: this.overlayName,
-            baseSchemataFolder: this.baseSchemataFolder
+            baseSchemataFolder: this.baseSchemataFolder,
+            gitlabProjectId: this.gitlabProjectId
           });
+          currentOverlay.gitlabProjectId = this.gitlabProjectId;
           this.overlays.push(currentOverlay);
         });
       }
@@ -9948,6 +10080,15 @@ import TabItem from '@theme/TabItem';
           });
         });
       }
+      /**
+       * Mark an attribute to be omitted from the resulting schema.
+       * @param {} attribute
+       */
+      deleteAttribute() {
+        this.overlays.forEach((overlay) => {
+          overlay.deleteAttribute(this.attribute);
+        });
+      }
       /**
        * Stores all involved schemas into the folder structure for `base schemata` (provided as the parameter `baseSchemataFolder`) which will be consumed by our conventions later.
        * @returns {} -- It returns objects containing all paths.
@@ -9960,21 +10101,21 @@ import TabItem from '@theme/TabItem';
         return output;
       }
     };
-    __name(_AttributeOverlay, "AttributeOverlay");
-    var AttributeOverlay = _AttributeOverlay;
+    __name(_InputConventionChanges, "InputConventionChanges");
+    var InputConventionChanges = _InputConventionChanges;
     exports.SchemaOverlay = SchemaOverlay;
     exports.ConventionSchema = ConventionSchema;
-    exports.AttributeOverlay = AttributeOverlay;
+    exports.InputConventionChanges = InputConventionChanges;
   }
 });
 
 // src/index.js
 var require_src = __commonJS({
   "src/index.js"(exports) {
-    var { SchemaOverlay, ConventionSchema, AttributeOverlay } = require_convention_builder();
+    var { SchemaOverlay, ConventionSchema, InputConventionChanges } = require_convention_builder();
     var schemaUtils = require_schema_utilities();
     exports.SchemaOverlay = SchemaOverlay;
-    exports.AttributeOverlay = AttributeOverlay;
+    exports.InputConventionChanges = InputConventionChanges;
     exports.ConventionSchema = ConventionSchema;
     exports.fixRelationshipDataField = schemaUtils.fixRelationshipDataField;
     exports.buildValidator = schemaUtils.buildValidator;

package/dist/node/index.js

@@ -8607,7 +8607,12 @@ var require_schema_utilities = __commonJS({
     __name(apiComposeTaxonomiesTransformation, "apiComposeTaxonomiesTransformation");
     function exampleImporter(filename, basePath = `${__dirname}/../../../definitions/examples/raw_examples_and_scripts/`, schemataSource = `${__dirname}/../../../input/collection`) {
       let rawData = JSON.parse(fs.readFileSync(`${basePath}/${filename}`)).map((obj) => {
-        let output = obj.entity;
+        let output = obj.entity ? obj.entity : obj;
+        if (!output) {
+          console.log(obj);
+          console.log(output);
+        }
+        ;
         if (output.attributes.relationships) {
           output.relationships = output.attributes.relationships;
           delete output.attributes.relationships;
@@ -8624,7 +8629,7 @@ var require_schema_utilities = __commonJS({
       });
       let newEntities = [];
       let entities = rawData.flatMap((entity) => {
-        let transformedData = apiComposeTaxonomiesTransformation(entity);
+        let transformedData = entity.relationships ? apiComposeTaxonomiesTransformation(entity) : { mainEntity: entity, newEntities: [] };
         return [transformedData.mainEntity, ...transformedData.newEntities];
       });
       return entities;
@@ -9045,6 +9050,20 @@ var require_schema_utilities = __commonJS({
       return output;
     }
     __name(findAllNonObjectAttributesInTree, "findAllNonObjectAttributesInTree");
+    function gitlabConventionURLTemplate({ conventionName, projectID }) {
+      return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/output/collection/conventions/${conventionName}/schema.json?job=copy_schemas`;
+    }
+    __name(gitlabConventionURLTemplate, "gitlabConventionURLTemplate");
+    function gitlabOverlayURLTemplate({ overlayName, projectID, baseEntityTypeAndbundle = "" }) {
+      return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/input/collection/${overlayName}/schema.json?job=copy_schemas`;
+    }
+    __name(gitlabOverlayURLTemplate, "gitlabOverlayURLTemplate");
+    function basicSchemaURLTemplate({ baseEntityTypeAndBundle, projectID }) {
+      let type = baseEntityTypeAndBundle.split("--")[0];
+      let bundle = baseEntityTypeAndBundle.split("--")[1];
+      return `https://gitlab.com/api/v4/projects/${projectID}/jobs/artifacts/main/raw/input/collection/${type}/${bundle}/schema.json?job=copy_schemas`;
+    }
+    __name(basicSchemaURLTemplate, "basicSchemaURLTemplate");
     exports2.dig = dig;
     exports2.bury = bury;
     exports2.fixRelationshipDataField = fixRelationshipDataField;
@@ -9067,6 +9086,9 @@ var require_schema_utilities = __commonJS({
     exports2.listAttributesAndSubAttributes = listAttributesAndSubAttributes;
     exports2.findAllObjectAttributesInTree = findAllObjectAttributesInTree;
     exports2.findAllNonObjectAttributesInTree = findAllNonObjectAttributesInTree;
+    exports2.gitlabConventionURLTemplate = gitlabConventionURLTemplate;
+    exports2.gitlabOverlayURLTemplate = gitlabOverlayURLTemplate;
+    exports2.basicSchemaURLTemplate = basicSchemaURLTemplate;
   }
 });
 
@@ -9081,7 +9103,11 @@ var require_convention_builder = __commonJS({
       bury,
       listAttributesAndSubAttributes,
       findAllObjectAttributesInTree,
-      findAllNonObjectAttributesInTree
+      findAllNonObjectAttributesInTree,
+      gitlabOverlayURLTemplate,
+      gitlabConventionURLTemplate,
+      basicSchemaURLTemplate,
+      arrayToStructuredConvention
     } = require_schema_utilities();
     function getAttributes(root, convention) {
       let branches = convention.relationships.filter((rel) => rel.containerEntity == root).map((d) => d.mentionedEntity);
@@ -9096,21 +9122,23 @@ var require_convention_builder = __commonJS({
         name,
         validExamples,
         erroredExamples,
-        repoURL,
+        repoURLTemplateFunction = gitlabOverlayURLTemplate,
         storageFolder = `${__dirname}/../../../../output/collection/overlays`,
         strictEnums = true,
         overlay = false,
         originalSrcScript,
         trivial = false,
         baseSchemataFolder = `${__dirname}/../../../../input/collection`,
+        gitlabProjectId = process.env.CI_PROJECT_ID,
         requiredFields = [],
-        modifiedAttributes
+        modifiedAttributes,
+        deletedAttributes = []
       }) {
         this.name = name;
         this.typeAndBundle = typeAndBundle;
         this.validExamples = validExamples;
         this.erroredExamples = erroredExamples;
-        this.repoURL = repoURL;
+        this.repoURLTemplateFunction = repoURLTemplateFunction;
         this.schemaName = `${typeAndBundle}--${name}`;
         this.storageFolder = storageFolder;
         this.strictEnums = strictEnums;
@@ -9140,6 +9168,7 @@ var require_convention_builder = __commonJS({
         this.baseSchema = baseSchema;
         this.unmodifiedAttributes = listAttributesAndSubAttributes(this.baseSchema);
         this.modifiedAttributes = modifiedAttributes ? modifiedAttributes : /* @__PURE__ */ new Set([]);
+        this.deletedAttributes = deletedAttributes;
         if (!overlay) {
           this.overlay = {
             properties: {
@@ -9171,8 +9200,8 @@ var require_convention_builder = __commonJS({
        */
       updateSchema() {
         this.schema = {};
-        this.schema.$id = `${this.repoURL}/schemata/${this.typeAndBundle.replace("--", "/")}/schema.json`;
         Object.assign(this.schema, this.baseSchema);
+        this.schema.$id = this.repoURLTemplateFunction({ overlayName: this.name, projectID: this.gitlabProjectId, baseEntityTypeAndBundle: this.typeAndBundle });
         let allModifiedAttributes = listAttributesAndSubAttributes(this.overlay);
         this.modifiedAttributes = allModifiedAttributes;
         this.unmodifiedAttributes = listAttributesAndSubAttributes(this.baseSchema);
@@ -9181,6 +9210,7 @@ var require_convention_builder = __commonJS({
           let currentValue = dig(this.overlay.properties.attributes.properties, attr);
           bury(this.schema, `properties.attributes.properties.${attr}`, currentValue, false);
         });
+        this.deletedAttributes.forEach((deletedAttr) => delete this.schema.properties.attributes.properties[deletedAttr]);
         let originalRequiredFields = this.schema.properties.attributes.required ? this.schema.properties.attributes.required : [];
         let allRequiredSet = Array.from(/* @__PURE__ */ new Set([...originalRequiredFields, ...Array.from(this.requiredFields)]));
         this.schema.properties.attributes.required = allRequiredSet;
@@ -9283,6 +9313,15 @@ var require_convention_builder = __commonJS({
         ;
         this.setGenericSection({ attribute, section: subschema, description });
       }
+      /**
+       * Mark an attribute to be omitted from the resulting schema.
+       * @param {} attribute
+       */
+      deleteAttribute(attribute) {
+        this.deletedAttributes.push(attribute);
+        delete this.overlay.properties.attributes.properties[attribute];
+        this.updateAttributeStatus(attribute);
+      }
       /**
        * Build an AJV validator and ensure all valid examples are accepted and all error examples are rejected. Returns an array attribute for each set of examples, plus a general success attribute indicating wether all examples resulted as expected and a failedExamples array only listing entities for which there was no success (meanin unrejected error examples and rejected valid examples).
        */
@@ -9373,16 +9412,18 @@ var require_convention_builder = __commonJS({
       constructor({
         typeAndBundle,
         attributeOverlayName,
-        repoURL,
+        repoURLTemplateFunction = basicSchemaURLTemplate,
         strictEnums = true,
-        baseSchemataFolder = `${__dirname}/../../../../input/collection`
+        baseSchemataFolder = `${__dirname}/../../../../input/collection`,
+        gitlabProjectId = process.env.CI_PROJECT_ID
       }) {
         super({
           typeAndBundle,
-          repoURL,
+          repoURLTemplateFunction,
           storageFolder: baseSchemataFolder,
           baseSchemataFolder,
-          strictEnums
+          strictEnums,
+          gitlabProjectId
         });
         this.attributeOverlayName = attributeOverlayName;
       }
@@ -9410,12 +9451,13 @@ var require_convention_builder = __commonJS({
         title,
         schemaName,
         version,
-        repoURL,
+        repoURLTemplateFunction = gitlabConventionURLTemplate,
         description,
-        validExamples,
-        erroredExamples,
+        validExamples = [],
+        erroredExamples = [],
         storageFolder = `${__dirname}/../../../../output/collection`,
         baseSchemataFolder = `${__dirname}/../../../../input/collection`,
+        gitlabProjectId = process.env.CI_PROJECT_ID,
         strictEnums = false,
         overlays = false,
         relationships = false,
@@ -9430,13 +9472,14 @@ var require_convention_builder = __commonJS({
         this.description = description;
         this.schemaName = schemaName;
         this.version = version;
-        this.repoURL = repoURL, this.validExamples = validExamples;
+        this.repoURLTemplateFunction = repoURLTemplateFunction, this.validExamples = validExamples;
         this.erroredExamples = erroredExamples;
         this.overlays = {};
         this.relationships = [];
         this.required = [];
         this.storageFolder = storageFolder;
         this.baseSchemataFolder = baseSchemataFolder;
+        this.gitlabProjectId = gitlabProjectId;
         if (overlays) {
           let overlayNames = Object.keys(overlays);
           this.overlays = {};
@@ -9512,7 +9555,7 @@ var require_convention_builder = __commonJS({
         this.schema = {
           title: this.title,
           type: "object",
-          $id: `${this.repoURL}/${this.version}/conventions/${this.schemaName}`,
+          $id: this.repoURLTemplateFunction({ conventionName: this.schemaName, projectID: this.gitlabProjectId }),
           $schema: "https://json-schema.org/draft/2020-12/schema",
           properties: {},
           description: this.description,
@@ -9737,17 +9780,102 @@ import TabItem from '@theme/TabItem';
         let body = [header, mainText, "# View Schema\n", "<Tabs>", schemaPluginInvocation, schemaPluginInvocationRequiredOnly, codeBlock, conventionAsText, "</Tabs>"].join("\n");
         return body;
       }
+      getExamplesFromFile({ path }) {
+        let isFolder = fs.lstatSync(path).isDirectory();
+        let isJSONFile = new RegExp(/\.json$/i).test(path);
+        let noFilesError = `The provided path (${path}) does not lead to JSON file nor a folder containing JSON files. Folder: ${isFolder}, JSON File: ${isJSONFile}`;
+        let output = [];
+        if (isFolder) {
+          let folderExamples = fs.readdirSync(path, (error, files) => {
+            return files;
+          }).filter((path2) => new RegExp(/\.json$/i).test(path2)).map((filename) => {
+            let examples = JSON.parse(fs.readFileSync(`${path}/${filename}`));
+            return examples;
+          });
+          if (folderExamples.length == 0) {
+            throw new Error(noFilesError);
+          }
+          ;
+          output.push(...folderExamples);
+        } else if (isJSONFile) {
+          let example = JSON.parse(fs.readFileSync(path));
+          output.push(example);
+        } else {
+          throw new Error(noFilesError);
+        }
+        ;
+        return output;
+      }
+      /**
+       * Will retrieve an individual example from a JSON file or all examples in a given folder. They all need to be either valid or invalid examples, and that should be indicated by the 'is_valid_example' attribute.
+       * @param {string} path -- A string representing an absolute path, leading to either a JSON file containing an individual example or a folder containing several examples. 
+       * @param {object|array} object -- Either an array of examples or an individual example. 
+       * @param {boolean} is_valid_example -- Whether to store the provided examples as valid examples or errors, for the tests.
+       * @param {boolean} structured_as_array -- Mark as "true" if the provided example is structured as a loose array of entities, as FarmOS delivers them (instead of structured as a convention object in which every entity is a property). The method will try to structure the entity and return meaningful information if it is not successful in doing so.
+       */
+      addExample({ path, object, is_valid_example, structured_as_array }) {
+        let output = {
+          success: false,
+          errors: []
+        };
+        if (!path && !object) {
+          throw new Error(`Either an object or a path leading to a folder or a json file need to be provided. Both arguments are empty.`);
+        }
+        ;
+        let newExamples = [];
+        if (object) {
+          if (!Array.isArray(object)) {
+            newExamples.push(object);
+          } else {
+            newExamples.push(...object);
+          }
+          ;
+        } else if (path) {
+          newExamples = this.getExamplesFromFile({ path });
+        }
+        ;
+        if (structured_as_array) {
+          newExamples = newExamples.map((exampleArray) => {
+            let exampleObject = arrayToStructuredConvention({
+              entitiesArray: exampleArray,
+              conventionObject: this
+            });
+            if (!exampleObject.is_valid && is_valid_example) {
+              output.errors.push("The `arrayToStructuredConvention` function wasn't able to rebuild a valid instance of this convention's schema from the provided array of loose entities. Look into the '.structuringAttempt' attribute for more information.");
+            }
+            ;
+            if (!is_valid_example) {
+              output.warning = "Since the example is not marked as 'valid', we can't check it is being properly parsed. Please review the output 'assembled_entity' to check it looks as it should.";
+            }
+            ;
+            output.structuringAttempt = exampleObject;
+            return exampleObject.assembled_entity;
+          });
+        }
+        ;
+        if (is_valid_example) {
+          this.validExamples.push(...newExamples);
+        } else {
+          this.erroredExamples.push(...newExamples);
+        }
+        ;
+        if (output.errors.length == 0) {
+          output.success = true;
+        }
+        ;
+        return output;
+      }
       /**
        * Build an AJV validator and ensure all valid examples are accepted and all error examples are rejected. Returns an array attribute for each set of examples, plus a general success attribute indicating wether all examples resulted as expected and a failedExamples array only listing entities for which there was no success (meanin unrejected error examples and rejected valid examples).
        */
       testExamples() {
         let generalOutput = {};
         if (!this.validExamples || !this.erroredExamples) {
-          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute`);
+          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute. Valid examples amount: ${this.validExamples ? this.validExamples.length : "validExamples is not an array"}, errored examples amount: ${this.erroredExamples ? this.erroredExamples.length : "erroredExamples is not an array"}.`);
         }
         ;
         if (this.validExamples.length == 0 || this.erroredExamples.length == 0) {
-          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute`);
+          throw new Error(`Testing can't happen because examples are missing either in the valid or errored attribute. Valid examples amount: ${this.validExamples ? this.validExamples.length : "validExamples is not an array"}, errored examples amount: ${this.erroredExamples ? this.erroredExamples.length : "erroredExamples is not an array"}.`);
         }
         ;
         this.updateSchema();
@@ -9853,7 +9981,7 @@ import TabItem from '@theme/TabItem';
     };
     __name(_ConventionSchema, "ConventionSchema");
     var ConventionSchema2 = _ConventionSchema;
-    var _AttributeOverlay = class _AttributeOverlay {
+    var _InputConventionChanges = class _InputConventionChanges {
       constructor({
         type,
         bundle,
@@ -9861,7 +9989,8 @@ import TabItem from '@theme/TabItem';
         baseSchemataFolder = `${__dirname}/../../../../input/collection`,
         sourceSchemataFile = `${__dirname}/../../../../input/farmos.json`,
         overlayName,
-        overlayDescription
+        overlayDescription,
+        gitlabProjectId = process.env.CI_PROJECT_ID
       }) {
         let integralSchemataFile = JSON.parse(fs.readFileSync(sourceSchemataFile));
         this.type = type;
@@ -9872,6 +10001,7 @@ import TabItem from '@theme/TabItem';
         this.sourceSchemata = integralSchemataFile;
         this.lexicon = [...findAllObjectAttributesInTree(this.sourceSchemata), ...findAllNonObjectAttributesInTree(this.sourceSchemata)];
         this.baseSchemataFolder = baseSchemataFolder;
+        this.gitlabProjectId = gitlabProjectId;
         let involvedSchemata = this.lexicon.filter((entry) => this.attribute == entry.attribute).flatMap((entry) => entry.instances).filter((instance) => this.type ? instance.type == this.type : true).filter((instance) => this.bundle ? instance.bundle == this.bundle : true).map((d) => d.schema);
         this.targetSchemata = Array.from(new Set(involvedSchemata));
         this.overlays = [];
@@ -9879,8 +10009,10 @@ import TabItem from '@theme/TabItem';
           let currentOverlay = new AttributePatchingSchemaOverlay({
             typeAndBundle: target,
             attributeOverlayName: this.overlayName,
-            baseSchemataFolder: this.baseSchemataFolder
+            baseSchemataFolder: this.baseSchemataFolder,
+            gitlabProjectId: this.gitlabProjectId
           });
+          currentOverlay.gitlabProjectId = this.gitlabProjectId;
           this.overlays.push(currentOverlay);
         });
       }
@@ -9941,6 +10073,15 @@ import TabItem from '@theme/TabItem';
           });
         });
       }
+      /**
+       * Mark an attribute to be omitted from the resulting schema.
+       * @param {} attribute
+       */
+      deleteAttribute() {
+        this.overlays.forEach((overlay) => {
+          overlay.deleteAttribute(this.attribute);
+        });
+      }
       /**
        * Stores all involved schemas into the folder structure for `base schemata` (provided as the parameter `baseSchemataFolder`) which will be consumed by our conventions later.
        * @returns {} -- It returns objects containing all paths.
@@ -9953,19 +10094,19 @@ import TabItem from '@theme/TabItem';
         return output;
       }
     };
-    __name(_AttributeOverlay, "AttributeOverlay");
-    var AttributeOverlay2 = _AttributeOverlay;
+    __name(_InputConventionChanges, "InputConventionChanges");
+    var InputConventionChanges2 = _InputConventionChanges;
     exports2.SchemaOverlay = SchemaOverlay2;
     exports2.ConventionSchema = ConventionSchema2;
-    exports2.AttributeOverlay = AttributeOverlay2;
+    exports2.InputConventionChanges = InputConventionChanges2;
   }
 });
 
 // src/index.js
-var { SchemaOverlay, ConventionSchema, AttributeOverlay } = require_convention_builder();
+var { SchemaOverlay, ConventionSchema, InputConventionChanges } = require_convention_builder();
 var schemaUtils = require_schema_utilities();
 exports.SchemaOverlay = SchemaOverlay;
-exports.AttributeOverlay = AttributeOverlay;
+exports.InputConventionChanges = InputConventionChanges;
 exports.ConventionSchema = ConventionSchema;
 exports.fixRelationshipDataField = schemaUtils.fixRelationshipDataField;
 exports.buildValidator = schemaUtils.buildValidator;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "convention_builder",
-    "version": "1.4.3",
+    "version": "1.5.0",
     "description": "Helper tools that offer a high level interface that transforms a convention description into it's json schema.",
     "main": "./dist/node/index.js",
     "browser": "./dist/browser/index.js",
@@ -42,6 +42,7 @@
         "jsdoc": "^4.0.2"
     },
     "devDependencies": {
+        "dotenv": "^16.4.5",
         "esbuild": "^0.19.7",
         "jest": "^29.7.0",
         "jest-junit": "^15.0.0",