Implement schema presets (#146)

action.yml

@@ -20,13 +20,16 @@ branding:
 
 inputs:
   csv:
-    description: >
-      Path(s) to validate. You can specify path in which CSV files will be searched.
-      Feel free to use glob pattrens. Usage examples:
-      /full/path/file.csv, p/file.csv, p/*.csv, p/**/*.csv, p/**/name-*.csv, **/*.csv, etc.
+    description: |
+      Specify the path(s) to the CSV files you want to validate.
+        This can include a direct path to a file or a directory to search with a maximum depth of 10 levels.
+        Examples: /full/path/name.csv; p/file.csv; p/*.csv; p/**/*.csv; p/**/name-*.csv; **/*.csv
     required: true
   schema:
-    description: 'Schema filepath. It can be a YAML, JSON or PHP. See examples on GitHub.'
+    description: |
+      Specify the path(s) to the schema file(s), supporting YAML, JSON, or PHP formats.
+        Similar to CSV paths, you can direct to specific files or search directories with glob patterns.
+        Examples: /full/path/name.yml; p/file.yml; p/*.yml; p/**/*.yml; p/**/name-*.yml; **/*.yml
     required: true
   report:
     description: 'Report format. Available options: text, table, github, gitlab, teamcity, junit.'
@@ -43,12 +46,15 @@ inputs:
 
   # Only for debbuging and profiling
   extra:
-    description: >
-      ANSI output. You can disable ANSI colors if you want with `--no-ansi`.
-      Verbosity level: Available options: `-v`, `-vv`, `-vvv`
-      Add flag `--profile` if you want to see profiling info. Add details with `-vvv`.
-      Add flag `--debug` if you want to see more really deep details.
-    default: 'extra: --ansi'
+    description: |
+      Extra options for the CSV Blueprint. Only for debbuging and profiling.
+      Available options:
+        ANSI output. You can disable ANSI colors if you want with `--no-ansi`.
+        Verbosity level: Available options: `-v`, `-vv`, `-vvv`.
+        Add flag `--profile` if you want to see profiling info. Add details with `-vvv`.
+        Add flag `--debug` if you want to see more really deep details.
+        Add flag `--dump-schema` if you want to see the final schema after all includes and inheritance.
+    default: 'options: --ansi'
 
 runs:
   using: 'docker'

schema-examples/full.json

@@ -2,9 +2,14 @@
     "name"             : "CSV Blueprint Schema Example",
     "description"      : "This YAML file provides a detailed description and validation rules for CSV files\nto be processed by CSV Blueprint tool. It includes specifications for file name patterns,\nCSV formatting options, and extensive validation criteria for individual columns and their values,\nsupporting a wide range of data validation rules from basic type checks to complex regex validations.\nThis example serves as a comprehensive guide for creating robust CSV file validations.\n",
 
+    "presets"          : {
+        "my-preset" : ".\/preset_users.yml"
+    },
+
     "filename_pattern" : "\/demo(-\\d+)?\\.csv$\/i",
 
     "csv"              : {
+        "preset"     : "my-preset",
         "header"     : true,
         "delimiter"  : ",",
         "quote_char" : "\\",
@@ -14,18 +19,21 @@
     },
 
     "structural_rules" : {
+        "preset"              : "my-preset",
         "strict_column_order" : true,
         "allow_extra_columns" : false
     },
 
     "columns"          : [
         {
+            "preset"          : "my-preset/login",
             "name"            : "Column Name (header)",
             "description"     : "Lorem ipsum",
             "example"         : "Some example",
             "required"        : true,
 
             "rules"           : {
+                "preset"                  : "my-preset/login",
                 "not_empty"               : true,
                 "exact_value"             : "Some string",
                 "allow_values"            : ["y", "n", ""],
@@ -147,9 +155,9 @@
                 "is_luhn"                 : true,
 
                 "phone"                   : "ALL",
+                "postal_code"             : "US",
                 "is_iban"                 : true,
                 "is_bic"                  : true,
-                "postal_code"             : "US",
                 "is_imei"                 : true,
                 "is_isbn"                 : true,
 
@@ -166,6 +174,7 @@
                 "credit_card"             : "Any"
             },
             "aggregate_rules" : {
+                "preset"                      : "my-preset/login",
                 "is_unique"                   : true,
                 "sorted"                      : ["asc", "natural"],
 

schema-examples/full.php

@@ -23,9 +23,14 @@
 This example serves as a comprehensive guide for creating robust CSV file validations.
 ',
 
+    'presets' => [
+        'my-preset' => './preset_users.yml',
+    ],
+
     'filename_pattern' => '/demo(-\\d+)?\\.csv$/i',
 
     'csv' => [
+        'preset'     => 'my-preset',
         'header'     => true,
         'delimiter'  => ',',
         'quote_char' => '\\',
@@ -35,18 +40,21 @@
     ],
 
     'structural_rules' => [
+        'preset'              => 'my-preset',
         'strict_column_order' => true,
         'allow_extra_columns' => false,
     ],
 
     'columns' => [
         [
+            'preset'      => 'my-preset/login',
             'name'        => 'Column Name (header)',
             'description' => 'Lorem ipsum',
             'example'     => 'Some example',
             'required'    => true,
 
             'rules' => [
+                'preset'           => 'my-preset/login',
                 'not_empty'        => true,
                 'exact_value'      => 'Some string',
                 'allow_values'     => ['y', 'n', ''],
@@ -167,9 +175,9 @@
                 'is_luhn'         => true,
 
                 'phone'       => 'ALL',
+                'postal_code' => 'US',
                 'is_iban'     => true,
                 'is_bic'      => true,
-                'postal_code' => 'US',
                 'is_imei'     => true,
                 'is_isbn'     => true,
 
@@ -188,6 +196,8 @@
             ],
 
             'aggregate_rules' => [
+                'preset' => 'my-preset/login',
+
                 'is_unique' => true,
                 'sorted'    => ['asc', 'natural'],
 

schema-examples/full.yml

@@ -22,15 +22,20 @@ description: |                          # Any description of the CSV file. Not u
   supporting a wide range of data validation rules from basic type checks to complex regex validations.
   This example serves as a comprehensive guide for creating robust CSV file validations.
 
+presets:                                # Include another schema and define an alias for it.
+  my-preset: ./preset_users.yml         # Define preset alias "my-preset". See README.md for details.
+
 # Regular expression to match the file name. If not set, then no pattern check.
 # This allows you to pre-validate the file name before processing its contents.
 # Feel free to check parent directories as well.
 # See: https://www.php.net/manual/en/reference.pcre.pattern.syntax.php
 filename_pattern: /demo(-\d+)?\.csv$/i
+#  preset: my-preset                    # See README.md for details.
 
 # Here are default values to parse CSV file.
 # You can skip this section if you don't need to override the default values.
 csv:
+  preset: my-preset                     # See README.md for details.
   header: true                          # If the first row is a header. If true, name of each column is required.
   delimiter: ,                          # Delimiter character in CSV file.
   quote_char: \                         # Quote character in CSV file.
@@ -42,6 +47,7 @@ csv:
 # They are not(!) related to the data in the columns.
 # You can skip this section if you don't need to override the default values.
 structural_rules: # Here are default values.
+  preset: my-preset                     # See README.md for details.
   strict_column_order: true             # Ensure columns in CSV follow the same order as defined in this YML schema. It works only if "csv.header" is true.
   allow_extra_columns: false            # Allow CSV files to have more columns than specified in this YML schema.
 
@@ -50,7 +56,8 @@ structural_rules: # Here are default values.
 # This will not affect the validator, but will make it easier for you to navigate.
 # For convenience, use the first line as a header (if possible).
 columns:
-  - name: Column Name (header)          # Any custom name of the column in the CSV file (first row). Required if "csv.header" is true.
+  - preset: my-preset/login             # Add preset rules for the column. See README.md for details.
+    name: Column Name (header)          # Any custom name of the column in the CSV file (first row). Required if "csv.header" is true.
     description: Lorem ipsum            # Description of the column. Not used in the validation process.
     example: Some example               # Example of the column value. Schema will also check this value on its own.
 
@@ -63,6 +70,8 @@ columns:
     # Data validation for each(!) value in the column. Please, see notes in README.md
     # Every rule is optional.
     rules:
+      preset: my-preset/login           # Add preset rules for the column. See README.md for details.
+
       # General rules
       not_empty: true                   # Value is not an empty string. Actually checks if the string length is not 0.
       exact_value: Some string          # Exact value for string in the column.
@@ -228,9 +237,9 @@ columns:
 
       # Identifications
       phone: ALL                        # Validates if the input is a phone number. Specify the country code to validate the phone number for a specific country. Example: "ALL", "US", "BR".".
+      postal_code: US                   # Validate postal code by country code (alpha-2). Example: "02179". Extracted from https://www.geonames.org
       is_iban: true                     # IBAN - International Bank Account Number. See: https://en.wikipedia.org/wiki/International_Bank_Account_Number
       is_bic: true                      # Validates a Bank Identifier Code (BIC) according to ISO 9362 standards. See: https://en.wikipedia.org/wiki/ISO_9362
-      postal_code: US                   # Validate postal code by country code (alpha-2). Example: "02179". Extracted from https://www.geonames.org
       is_imei: true                     # Validates an International Mobile Equipment Identity (IMEI). See: https://en.wikipedia.org/wiki/International_Mobile_Station_Equipment_Identity
       is_isbn: true                     # Validates an International Standard Book Number (ISBN). See: https://www.isbn-international.org/content/what-isbn
 
@@ -271,6 +280,8 @@ columns:
     # Data validation for the entire(!) column using different data aggregation methods.
     # Every rule is optional.
     aggregate_rules:
+      preset: my-preset/login           # Add preset aggregate rules for the column. See README.md for details.
+
       is_unique: true                   # All values in the column are unique.
 
       # Check if the column is sorted in a specific order.

schema-examples/full_clean.yml

@@ -21,9 +21,13 @@ description: |
   supporting a wide range of data validation rules from basic type checks to complex regex validations.
   This example serves as a comprehensive guide for creating robust CSV file validations.
 
+presets:
+  my-preset: ./preset_users.yml
+
 filename_pattern: '/demo(-\d+)?\.csv$/i'
 
 csv:
+  preset: my-preset
   header: true
   delimiter: ','
   quote_char: \
@@ -32,16 +36,19 @@ csv:
   bom: false
 
 structural_rules:
+  preset: my-preset
   strict_column_order: true
   allow_extra_columns: false
 
 columns:
-  - name: 'Column Name (header)'
+  - preset: my-preset/login
+    name: 'Column Name (header)'
     description: 'Lorem ipsum'
     example: 'Some example'
     required: true
 
     rules:
+      preset: my-preset/login
       not_empty: true
       exact_value: 'Some string'
       allow_values: [ 'y', 'n', '' ]
@@ -161,9 +168,9 @@ columns:
       is_luhn: true
 
       phone: ALL
+      postal_code: US
       is_iban: true
       is_bic: true
-      postal_code: US
       is_imei: true
       is_isbn: true
 
@@ -182,6 +189,7 @@ columns:
       credit_card: Any
 
     aggregate_rules:
+      preset: my-preset/login
       is_unique: true
       sorted: [ asc, natural ]
       first_num_min: 1.0

schema-examples/preset_database.yml

@@ -0,0 +1,34 @@
+#
+# JBZoo Toolbox - Csv-Blueprint.
+#
+# This file is part of the JBZoo Toolbox project.
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+# @license    MIT
+# @copyright  Copyright (C) JBZoo.com, All rights reserved.
+# @see        https://github.com/JBZoo/Csv-Blueprint
+#
+
+name: Presets for database columns
+description: This schema contains basic rules for database user data.
+
+columns:
+  - name: id
+    description: Unique identifier, usually used to denote a primary key in databases.
+    example: 12345
+    rules:
+      not_empty: true
+      is_trimmed: true
+      is_int: true
+      num_min: 1
+    aggregate_rules:
+      is_unique: true
+      sorted: [ asc, numeric ]
+
+  - name: status
+    description: Status in database
+    example: active
+    rules:
+      not_empty: true
+      allow_values: [ active, inactive, pending, deleted ]

schema-examples/preset_features.yml

@@ -0,0 +1,68 @@
+#
+# JBZoo Toolbox - Csv-Blueprint.
+#
+# This file is part of the JBZoo Toolbox project.
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+#
+# @license    MIT
+# @copyright  Copyright (C) JBZoo.com, All rights reserved.
+# @see        https://github.com/JBZoo/Csv-Blueprint
+#
+
+name: Complite list of preset features
+description: This schema contains all the features of the presets.
+
+presets:
+  # The basepath for the preset is `.` (current directory of the current schema file).
+  # Define alias "db" for schema in `./preset_database.yml`.
+  db: preset_database.yml           # Or `db: ./preset_database.yml`. It's up to you.
+
+  # For example, you can use a relative path.
+  users: ./../schema-examples/preset_users.yml
+
+  # Or you can use an absolute path.
+  # db: /full/path/preset_database.yml
+
+filename_pattern: { preset: users } # Take the filename pattern from the preset.
+structural_rules: { preset: users } # Take the global rules from the preset.
+csv: { preset: users }              # Take the CSV settings from the preset.
+
+columns:
+  # Use name of column from the preset.
+  # "db" is alias. "id" is column `name` in `preset_database.yml`.
+  - preset: 'db/id'
+
+  # Use column index. "db" is alias. "0" is column index in `preset_database.yml`.
+  - preset: 'db/0'
+  - preset: 'db/0:'
+
+  # Use column index and column name. It useful if column name is not unique.
+  - preset: 'db/0:id'
+
+  # Use only `rules` of "status" column from the preset.
+  - name: My column
+    rules:
+      preset: 'db/status'
+
+  # Override only `aggregate_rules` from the preset.
+  # Use only `aggregate_rules` of "id" column from the preset.
+  # We strictly take only the very first column (index = 0).
+  - name: My column
+    aggregate_rules:
+      preset: 'db/0:id'
+
+  # Combo!!! If you're a risk-taker or have a high level of inner zen. :)
+  # Creating a column from three other columns.
+  # In fact, it will merge all three at once with key replacement.
+  - name: Crazy combo!
+    description: >                  # Just a great advice.
+      I like to take risks, too.
+      Be careful. Use your power wisely.
+    example: ~                      # Ignore inherited "example" value. Set it `null`.
+    preset: 'users/login'
+    rules:
+      preset: 'users/email'
+      not_empty: true               # Disable the rule from the preset.
+    aggregate_rules:
+      preset: 'db/0'