diff --git a/README.md b/README.md index 5dc0b2f1..3743a932 100644 --- a/README.md +++ b/README.md @@ -900,25 +900,20 @@ These additional checks further secure the integrity and consistency of your CSV Presets enhance the efficiency and reusability of schema definitions for CSV file validation, streamlining the validation process across various files and schemas. Their benefits include: -- **Consistency Across Schemas**: Presets guarantee uniform validation rules for common fields like user IDs, email +- **Consistency Across Schemas:** Presets guarantee uniform validation rules for common fields like user IDs, email addresses, and phone numbers across different CSV files. This consistency is crucial for maintaining data integrity and reliability. - -- **Ease of Maintenance**: Centralized updates to presets automatically propagate changes to all schemas using them. +- **Ease of Maintenance:** Centralized updates to presets automatically propagate changes to all schemas using them. This approach eliminates the need to manually update each schema, significantly reducing maintenance efforts. - -- **Flexibility and Customization**: While offering a foundational set of validation rules, presets also allow for +- **Flexibility and Customization:** While offering a foundational set of validation rules, presets also allow for field-specific rule overrides to meet the unique requirements of individual schemas. This ensures a balance between consistency and customization. - -- **Rapid Development**: Presets facilitate quick schema setup for new CSV files by reusing established +- **Rapid Development:** Presets facilitate quick schema setup for new CSV files by reusing established validation rules. This allows for a faster development cycle, focusing on unique fields without redefining common rules. - -- **Error Reduction**: Utilizing consistent and tested presets reduces the likelihood of errors in manual schema +- **Error Reduction:** Utilizing consistent and tested presets reduces the likelihood of errors in manual schema definitions, leading to improved data quality and reliability. - -- **Efficiency in Large-scale Projects**: In large projects with extensive data volumes, presets provide a standardized +- **Efficiency in Large-scale Projects:** In large projects with extensive data volumes, presets provide a standardized approach to applying common validation logic, simplifying data management and validation tasks. Overall, presets offer a compelling solution for anyone involved in CSV file validation, enhancing consistency, maintenance, flexibility, development speed, error minimization, and project efficiency. @@ -929,16 +924,19 @@ Overall, presets offer a compelling solution for anyone involved in CSV file val Let's look at a real life example. Suppose you have a "library" of different user profile validation rules that can be used in a wide variety of CSV files. -In order not to care about integrity and not to suffer from copy and paste, you can reuse any existing schema. +In order not to care about integrity and not to suffer from copy and paste, you can reuse ANY(!) existing schema. In fact, this can be considered as partial inheritance. **Important notes** - - You can make the chain of inheritance infinitely long (of course if you like to take risks). - - Any of the files can be used alone or as a library. The syntax is the same. + - You can make the chain of inheritance infinitely long. + I.e. make chains of the form `grant-parent.yml` -> `parent.yml` -> `child.yml` -> `grandchild.yml` -> `great-grandchild.yml` -> etc. + Of course if you like to take risks ;). + - Any(!) of the schema files can be used alone or as a library. The syntax is the same. - Schemas with presets validate themselves and if there are any obvious issues, you will see them when you try to use - the schema. + the schema. But logical conflicts between rules are not checked (It's almost impossible from a code perspective). + As mentioned above, rules work in isolation and are not aware of each other. So the set of rules is your responsibility as always. - Alias in presets must match the regex pattern - `"/^[a-z0-9-_]+$/i"` . + "/^[a-z0-9-_]+$/i". Otherwise, it might break the syntax. @@ -951,7 +949,7 @@ As a result, you don't just get a bunch of schemas for validation, which is diff framework(!) that will be targeted to the specifics of your project, especially when there are dozens or even hundreds of CSV files and rules. It will be much easier to achieve consistency. Very often it's quite important. -[preset_database.yml](schema-examples/preset_database.yml) +[Database preset](schema-examples/preset_database.yml) ```yml name: Presets for database columns @@ -979,11 +977,13 @@ columns: ``` -[preset_users.yml](schema-examples/preset_users.yml) +[User data preset](schema-examples/preset_users.yml) ```yml name: Common presets for user data -description: This schema contains common presets for user data. It can be used as a base for other schemas. +description: > + This schema contains common presets for user data. + It can be used as a base for other schemas. filename_pattern: /users-.*\.csv$/i @@ -1086,7 +1086,7 @@ columns: -[preset_usage.yml](schema-examples/preset_usage.yml) +[Usage of presets](schema-examples/preset_usage.yml) ```yml name: Schema uses presets and add new columns + specific rules. @@ -1126,7 +1126,7 @@ columns: - name: phone # Overridden value preset: users/phone_number - - name: admin_note + - name: admin_note # New column specific only this schema description: Admin note rules: not_empty: true @@ -1142,7 +1142,7 @@ As a result, readability and maintainability became dramatically easier. You can easily add new rules, change existing, etc. -### Complete example with all available syntax of presets +### Complete example with all available syntax ```yml @@ -1150,58 +1150,64 @@ 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) - # Define alias "db" for schema in `./preset_database.yml` - db: preset_database.yml # Or just `db: preset_database.yml`. It's up to you. + # 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 + # For example, you can use a relative path. users: ./../schema-examples/preset_users.yml - # Or you can use an absolute path - # db-3: /full/path/preset_database.yml - - # Or you can use an absolute path + # Or you can use an absolute path. # db: /full/path/preset_database.yml filename_pattern: - preset: users # Take the filename pattern from the preset + preset: users # Take the filename pattern from the preset. csv: - preset: users # Take the CSV settings from the preset + 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` + # 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` + # 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' - # Override only `rules` from the preset + # Use only `rules` of "status" column from the preset. - name: My column rules: preset: 'db/status' - # Override only `aggregate_rules` from the preset + # 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. :) + # 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! - example: ~ + 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' ``` +**Note:** All provided YAML examples pass built-in validation, yet they may not make practical sense. +These are intended solely for demonstration and to illustrate potential configurations and features. ## Complete CLI help message diff --git a/schema-examples/preset_features.yml b/schema-examples/preset_features.yml index 34e22436..37f33b7b 100644 --- a/schema-examples/preset_features.yml +++ b/schema-examples/preset_features.yml @@ -14,52 +14,56 @@ 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) - # Define alias "db" for schema in `./preset_database.yml` - db: preset_database.yml # Or just `db: preset_database.yml`. It's up to you. + # 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 + # For example, you can use a relative path. users: ./../schema-examples/preset_users.yml - # Or you can use an absolute path - # db-3: /full/path/preset_database.yml - - # Or you can use an absolute path + # Or you can use an absolute path. # db: /full/path/preset_database.yml filename_pattern: - preset: users # Take the filename pattern from the preset + preset: users # Take the filename pattern from the preset. csv: - preset: users # Take the CSV settings from the preset + 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` + # 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` + # 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' - # Override only `rules` from the preset + # Use only `rules` of "status" column from the preset. - name: My column rules: preset: 'db/status' - # Override only `aggregate_rules` from the preset + # 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. :) + # 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! - example: ~ + 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' diff --git a/schema-examples/preset_usage.yml b/schema-examples/preset_usage.yml index 4bdae994..f0f22e34 100644 --- a/schema-examples/preset_usage.yml +++ b/schema-examples/preset_usage.yml @@ -47,7 +47,7 @@ columns: - name: phone # Overridden value preset: users/phone_number - - name: admin_note + - name: admin_note # New column specific only this schema description: Admin note rules: not_empty: true diff --git a/schema-examples/preset_users.yml b/schema-examples/preset_users.yml index 75782854..1d7a263e 100644 --- a/schema-examples/preset_users.yml +++ b/schema-examples/preset_users.yml @@ -11,7 +11,9 @@ # name: Common presets for user data -description: This schema contains common presets for user data. It can be used as a base for other schemas. +description: > + This schema contains common presets for user data. + It can be used as a base for other schemas. filename_pattern: /users-.*\.csv$/i diff --git a/tests/ReadmeTest.php b/tests/ReadmeTest.php index bf88009f..8fe79622 100644 --- a/tests/ReadmeTest.php +++ b/tests/ReadmeTest.php @@ -196,7 +196,7 @@ public function testCheckPresetFeaturesExampleInReadme(): void public function testCheckPresetRegexInReadme(): void { $text = SchemaDataPrep::getAliasRegex(); - Tools::insertInReadme('preset-regex', " `\"{$text}\"` ", true); + Tools::insertInReadme('preset-regex', "\"{$text}\"", true); } public function testCheckPresetDatabaseExampleInReadme(): void