# cnabio/cnab-spec architecture

> Architecture diagram of the GitHub repository cnabio/cnab-spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cnabio/cnab-spec
- Repository: https://github.com/cnabio/cnab-spec

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CNAB Specification Documents"
        Spec100["100-CNAB.md"]:::doc
        Spec200["200-CNAB-registries.md"]:::doc
        Spec300["300-CNAB-security.md"]:::doc
        Spec400["400-claims.md"]:::doc
        Spec500["500-CNAB-dependencies.md"]:::doc
        Spec801["801-declarative-images.md"]:::doc
        Spec101["101-bundle-json.md"]:::doc
        Spec102["102-invocation-image.md"]:::doc
    end

    subgraph "JSON Schemas"
        BundleSchema["bundle.schema.json"]:::schema
        ClaimSchema["claim.schema.json"]:::schema
        ClaimResultSchema["claim-result.schema.json"]:::schema
        DefinitionsSchema["definitions.schema.json"]:::schema
        DependenciesSchema["dependencies.schema.json"]:::schema
        ParameterSourcesSchema["parameter-sources.schema.json"]:::schema
        RelocationMappingSchema["relocation-mapping.schema.json"]:::schema
        StatusSchema["status.schema.json"]:::schema
    end

    subgraph "Example Artifacts"
        Example10101["101.01-bundle.json"]:::example
        Example10102["101.02-bundle.json"]:::example
        Example10103["101.03-bundle.json"]:::example
        ExamplesDir["examples/"]:::example
    end

    subgraph "Tooling & Automation"
        Makefile["Makefile"]:::tool
        Dockerfile["Dockerfile.ajv"]:::tool
        BrigadeJS["brigade.js"]:::tool
        BrigadeJSON["brigade.json"]:::tool
        Scripts["scripts/"]:::tool
    end

    subgraph "Repository Metadata & Governance"
        Contributing["CONTRIBUTING.md"]:::governance
        Governance["governance.md"]:::governance
        Owners["OWNERS"]:::governance
        CodeOwners[".github/CODEOWNERS"]:::governance
        Process["901-process.md"]:::governance
    end

    subgraph "CI/CD & Integration"
        Github[".github"]:::cicd
    end

    %% Relationships
    Spec100 -->|"specifies"| BundleSchema
    Spec100 -->|"applies"| ExamplesDir
    Makefile -->|"validates"| BundleSchema
    ExamplesDir -->|"illustrates"| BundleSchema
    Github -->|"triggers"| Makefile
    Contributing -->|"oversees"| Github
    Contributing -->|"contributes"| Spec100

    %% Click Events for CNAB Specification Documents
    click Spec100 "https://github.com/cnabio/cnab-spec/blob/main/100-CNAB.md"
    click Spec200 "https://github.com/cnabio/cnab-spec/blob/main/200-CNAB-registries.md"
    click Spec300 "https://github.com/cnabio/cnab-spec/blob/main/300-CNAB-security.md"
    click Spec400 "https://github.com/cnabio/cnab-spec/blob/main/400-claims.md"
    click Spec500 "https://github.com/cnabio/cnab-spec/blob/main/500-CNAB-dependencies.md"
    click Spec801 "https://github.com/cnabio/cnab-spec/blob/main/801-declarative-images.md"
    click Spec101 "https://github.com/cnabio/cnab-spec/blob/main/101-bundle-json.md"
    click Spec102 "https://github.com/cnabio/cnab-spec/blob/main/102-invocation-image.md"

    %% Click Events for JSON Schemas
    click BundleSchema "https://github.com/cnabio/cnab-spec/tree/main//schema"
    
    %% Click Events for Example Artifacts
    click Example10101 "https://github.com/cnabio/cnab-spec/tree/main//examples"
    click Example10102 "https://github.com/cnabio/cnab-spec/tree/main//examples"
    click Example10103 "https://github.com/cnabio/cnab-spec/tree/main//examples"
    click ExamplesDir "https://github.com/cnabio/cnab-spec/tree/main//examples"

    %% Click Events for Tooling & Automation
    click Makefile "https://github.com/cnabio/cnab-spec/tree/main/Makefile"
    click Dockerfile "https://github.com/cnabio/cnab-spec/blob/main/Dockerfile.ajv"
    click BrigadeJS "https://github.com/cnabio/cnab-spec/blob/main/brigade.js"
    click BrigadeJSON "https://github.com/cnabio/cnab-spec/blob/main/brigade.json"
    click Scripts "https://github.com/cnabio/cnab-spec/tree/main//scripts"

    %% Click Events for Repository Metadata & Governance
    click Contributing "https://github.com/cnabio/cnab-spec/blob/main/CONTRIBUTING.md"
    click Governance "https://github.com/cnabio/cnab-spec/blob/main/governance.md"
    click Owners "https://github.com/cnabio/cnab-spec/tree/main/OWNERS"
    click CodeOwners "https://github.com/cnabio/cnab-spec/tree/main/.github/CODEOWNERS"
    click Process "https://github.com/cnabio/cnab-spec/blob/main/901-process.md"

    %% Click Event for CI/CD & Integration
    click Github "https://github.com/cnabio/cnab-spec/blob/main/.github"

    %% Styles
    classDef doc fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
    classDef schema fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef example fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef tool fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef governance fill:#F5B041,stroke:#D35400,stroke-width:2px;
    classDef cicd fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
```
