How cnabio/cnab-spec works
Main Components
• Specification Documents – The major chapters are separated numerically (e.g., 100-CNAB.md, 200-CNAB-registries.md, 300-CNAB-security.md, 400-claims.md, 500-CNAB-dependencies.md, etc.). Each chapter forms a distinct component that defines core aspects of the CNAB specification.
• Schema Definitions – The /schema directory holds JSON schema files (e.g., bundle.schema.json, claim.schema.json, etc.) that provide formal structure and validation rules for CNAB artifacts.
• Example Files – The /examples directory contains sample JSON files demonstrating bundles, claim results, and other CNAB components. This illustrates usage scenarios of the specification.
• Tooling & Scripts – Files like Makefile, Dockerfile.ajv, brigade.js, brigade.json, and the /scripts directory represent tooling for validation, building, and testing the specifications (including URLs validations and schema compliance).
• Repository Metadata & Governance – Documents like CONTRIBUTING.md, GOVERNANCE.md, OWNERS, CODEOWNERS, and process files (e.g., 901-process.md) show how contributions, versioning, and governance are managed.
• CI/CD & Integration – The presence of a .github folder indicates integration with GitHub workflows for continuous integration, automated testing, and pull-request reviews.
Relationships and Interactions
• The Specification Documents reference one another to provide combined guidance (for instance, one document might detail how the bundle.json is structured, while another covers security or claimed artifacts).
• Schemas are used by tooling (Makefile, Dockerfile.ajv, scripts) to validate that the sample and user-supplied CNAB files conform to the defined standards.
• Example files act as a practical demonstration of using the CNAB spec definitions; these examples help link the documentation to real-world usage.
• CI/CD integrations (Brigade, GitHub workflows) help automate testing and validation of changes, ensuring that modifications to the spec or schemas remain compliant before merging.
Architectural Patterns and Design Principles
• Modular Organization – The project cleanly separates the specification chapters (by numbering and semantic purpose), the schemas, and the examples. This modular approach aligns with good separation-of-concerns practices.
• Declarative Validation – The JSON schema files enforce a declarative approach to validating CNAB artifacts, with tooling scripts wired to run these validations.
• Version Control and Branching – The README’s information on branch/tag structure emphasizes that the repository follows proper versioning practices, which is an integral piece of the system’s design.
Detail
• Don’t oversimplify; include as many discrete modules as the repository provides. The separation into chapters, schema definitions, examples, and automation scripts is fundamental for a detailed design.
• Remember to capture how versioning fits into the design, especially noting that the branch/tag strategy (as seen in the README’s section on Branch/Tag Structure) informs how the specification evolves.