How packetcoders/net-schema works
Project Type and Purpose
• Project Type: A Python-based library and CLI tool.
• Purpose: Validate JSON/YAML documents against a defined schema (leveraging JSON Schema) and apply custom validators (for network-specific data like ASN, IP, and VLAN). The tool also supports an option to check for duplicate keys.
File Structure
• Top-Level Files: Configuration files such as .flake8, .gitignore, Makefile, LICENSE, and pyproject.toml indicate standard Python project setup and CI configurations.
• Directories Breakdown:
• src: Contains core source code including:
▪ main.py – Likely the entry point for the CLI.
▪ helpers.py – Contains supportive utility functions.
▪ plugins/json_schema: Houses modules for custom validator implementations (asn.py, ip.py, validator.py, vlan.py). This indicates the use of a plugin-like architecture to extend JSON Schema with network-specific validations.
• examples: Provides sample host variables (YAML) and a sample schema file, which helps understand inputs and usage.
• tests: Contains test suites and fixtures – validating different aspects of the code (helpers, each plugin validator, etc.).
• .github/workflows: CI/CD pipeline configurations.
README for Additional Insights
• The README explains the project’s usage via CLI, installation instructions, and examples.
• It lists out custom validators (for ASN, IP, and VLAN), suggesting that these are core to the system’s operation.
• The descriptions help confirm that the primary interaction model is through command-line invocation, leveraging the main entry point and plugins.
a. Main Components:
• CLI Interface:
• Represented by the command-line entry point (src/main.py) that parses user arguments (document and schema paths, dup key option).
• Core Validation Engine:
• Includes core logic defined in src/helpers.py and orchestrated via main.py.
• This orchestrates reading input files, applying the JSON Schema validations, and using custom validators.
• Plugin System for Custom Validators:
• Represented by modules under src/plugins/json_schema/.
• Includes dedicated components for asn, ip, and vlan validation.
• Input and Output:
• Input: Document files and Schema file (illustrated by the examples directory).
• Output: Validation results (success or error messages).
• Testing Framework:
• Tests directory ensures functional correctness of each component.
b. Relationships and Interactions:
• The CLI initiates the process by invoking main.py.
• The main module uses helper functions to load and parse the documents and schema.
• The JSON Schema validator (plugin system) is invoked to check conformity to standard rules.
• Custom validator plugins (asn.py, ip.py, vlan.py) are then triggered when their keys are detected in the schema; they validate specialized network data rules.
• The results and any validation errors are then collected and output to the user.
• CI/CD and tests components ensure that each portion (core logic and plugins) is continually validated.
c. Architectural Patterns & Design Principles:
• Modularity: Separation between core validation logic (in main and helpers) and specialized validators (as plugins).
• Extensibility: Clear plugin structure that allows adding additional domain-specific checks without altering the core engine.
• Maintainability: Well-structured directories (src, tests, examples) indicate a clear separation of concerns.
d. Relevant Technologies and Frameworks:
• Python as the primary language.
• JSON Schema for document validation.
• Standard packaging tools (pip, poetry) and CI/CD (GitHub workflows).
• Testing frameworks (pytest implied by test files).