{"content":"# aux4/validator\n\naux4 data validator\n\naux4/validator validates JSON input against rule definitions (typically stored in an aux4 config). It integrates with aux4/config to extract rule sets from your configuration and provides streaming and filtering options so you can validate large data sets or pipeline results easily.\n\n## Installation\n\n``bash\naux4 aux4 pkger install aux4/validator\n`\n\n## Quick Start\n\nCreate a config.yaml with your rule definitions (see Configuration below). Then validate JSON input from a file or a pipeline:\n\n`bash\ncat person.json \\\n | aux4 aux4 validator validate --config data --rules person --ignore --onlyValid | jq .\n`\n\nThis will output only the valid items from the person rule set.\n\n## Usage\n\naux4/validator exposes a single profile of commands for validating JSON input.\n\n### Main Commands\n\n- [aux4 aux4 validator validate](./commands/validator/validate) - Validate JSON input against a named rule set.\n\n### Command Reference\n\naux4 aux4 validator validate\n\nDescription: Validate JSON input. The command reads JSON from stdin (either an array or newline-delimited JSON when --stream is used) and validates each item according to the rule mapping extracted from your aux4 config.\n\nVariables (defined in the package):\n\n- --rules (required) - Rule set name within the configuration. This is the set of validation rules to apply (see Configuration examples).\n- --lang (optional, default: en) - Validation language for error messages.\n- --stream (optional, default: false) - Treat stdin as a stream of newline-delimited JSON objects (instead of a single JSON array).\n- --ignore (optional, default: false) - Ignore validation errors and exit with code 0 (useful when you only want filtered output).\n- --silent (optional, default: false) - Suppress all output.\n- --onlyValid (optional, default: false) - Output only valid items.\n- --onlyInvalid (optional, default: false) - Output only invalid items (emits error objects to stderr when not using --ignore).\n\nNote: This package depends on aux4/config to extract configuration sections. Use the --config option (provided by aux4/config) to point to the config section that contains your rule definitions (for example --config data).\n\n## Examples\n\nThe examples below are lifted from the package tests and show common workflows.\n\n### Example config (config.yaml)\n\n`yaml\nconfig:\n data:\n person:\n name:\n path: $.name\n rule: required\n age:\n path: $.age\n rule: required|integer|min:18\n`\n\nSave this as config.yaml and make it available to aux4 (via your project config mechanism or aux4/config).\n\nCreate person.json:\n\n`json\n[\n {\"name\": \"John\", \"age\": 25},\n {\"name\": \"Eve\", \"age\": 6},\n {\"name\": \"Stella\",\"age\": 39}\n]\n`\n\n### Get only valid entries\n\n`bash\ncat person.json \\\n | aux4 aux4 validator validate --config data --rules person --ignore --onlyValid | jq .\n`\n\nOutput:\n\n`json\n[\n {\"name\":\"John\",\"age\":25},\n {\"name\":\"Stella\",\"age\":39}\n]\n`\n\n### Get only invalid entries (with errors)\n\n`bash\ncat person.json \\\n | aux4 aux4 validator validate --config data --rules person --onlyInvalid 2>&1 | jq .\n`\n\nOutput (example):\n\n`json\n[\n {\n \"item\": {\"name\":\"Eve\",\"age\":6},\n \"errors\": {\n \"age\": [\"The age must be at least 18.\"]\n }\n }\n]\n`\n\n### Stream mode (newline-delimited JSON)\n\n`bash\ncat person.json \\\n | aux4 aux4 validator validate --config data --rules person --stream --ignore --onlyValid | jq .\n`\n\nOutput (each valid item emitted separately):\n\n`json\n{ \"name\": \"John\", \"age\": 25 }\n{ \"name\": \"Stella\", \"age\": 39 }\n`\n\n## Advanced: Nested objects and arrays\n\nYou can define nested mappings and arrays in your rule set. Example rules (in config.yaml):\n\n`yaml\nconfig:\n data:\n nested-fields:\n name:\n path: $.name\n rule: \"alpha|required\"\n age:\n path: $.age\n rule: \"integer\"\n address:\n path: $.address\n mapping:\n street:\n path: $.street\n rule: \"required\"\n city:\n path: $.city\n rule: \"required\"\n state:\n path: $.state\n rule: \"required\"\n zip:\n path: $.zip\n rule: \"integer|required\"\n nested-array:\n name:\n path: $.name\n rule: \"alpha|required\"\n age:\n path: $.age\n rule: \"integer\"\n contacts:\n path: $.contacts\n type: array\n mapping:\n email:\n path: $.email\n rule: \"email|required\"\n phone:\n path: $.phone\n rule: \"required\"\n`\n\nValidate nested objects or arrays the same way:\n\n`bash\necho '[{\"name\":\"John\",\"age\":25,\"address\":{\"street\":\"123 Main St\",\"city\":\"Boston\",\"state\":\"MA\",\"zip\":12345}}]' \\\n | aux4 aux4 validator validate --config data --rules nested-fields --ignore --onlyValid | jq .\n`\n\nExpected output: the reconstructed, validated object.\n\n## Configuration\n\naux4/validator expects your validation rule sets to be available inside your aux4 configuration (for example under config.data). Each rule set is a mapping of field names to objects specifying path, rule, and optionally type and mapping for nested structures. See the test/*.test.md files in this package for many real examples you can copy.\n\n### Minimal rule entry\n\n`yaml\nfieldName:\n path: $.json.path\n rule: \"required|integer\"\n`\n\n## Package manifest (.aux4)\n\nBelow is the package .aux4 manifest that defines profiles, commands and variables for this package.\n\n`json\n{\n \"scope\": \"aux4\",\n \"name\": \"validator\",\n \"version\": \"1.1.0\",\n \"description\": \"aux4 data validator\",\n \"dependencies\": [\n \"aux4/config\"\n ],\n \"tags\": [\n \"aux4\",\n \"validator\",\n \"data\",\n \"json\"\n ],\n \"profiles\": [\n {\n \"name\": \"main\",\n \"commands\": [\n {\n \"name\": \"validator\",\n \"execute\": [\n \"profile:validator\"\n ],\n \"help\": {\n \"text\": \"aux4 data validator\"\n }\n }\n ]\n },\n {\n \"name\": \"validator\",\n \"commands\": [\n {\n \"name\": \"validate\",\n \"execute\": [\n \"stdin:node ${packageDir}/lib/aux4-validator.mjs validate value($rules) values(lang, stream, ignore, silent, onlyValid, onlyInvalid)\"\n ],\n \"help\": {\n \"text\": \"validate json input\",\n \"variables\": [\n {\n \"name\": \"rules\",\n \"text\": \"Validation rules\"\n },\n {\n \"name\": \"lang\",\n \"text\": \"Validator language\",\n \"default\": \"en\"\n },\n {\n \"name\": \"stream\",\n \"text\": \"Stream input\",\n \"default\": \"false\"\n },\n {\n \"name\": \"ignore\",\n \"text\": \"Ignore errors (always exit code 0)\",\n \"default\": \"false\"\n },\n {\n \"name\": \"silent\",\n \"text\": \"Does not output anything\",\n \"default\": \"false\"\n },\n {\n \"name\": \"onlyValid\",\n \"text\": \"Output only valid data\",\n \"default\": \"false\"\n },\n {\n \"name\": \"onlyInvalid\",\n \"text\": \"Output only invalid data\",\n \"default\": \"false\"\n }\n ]\n }\n }\n ]\n }\n ]\n}\n``\n\n## See Also\n\n- aux4/config - extract configuration sections used by this validator\n\n## License\n\nThis package is licensed under the Apache License, Version 2.0.\n\n\n"}