# awslabs/aws-config-resource-schema architecture

> Architecture diagram of the GitHub repository awslabs/aws-config-resource-schema, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awslabs/aws-config-resource-schema
- Repository: https://github.com/awslabs/aws-config-resource-schema

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **not an application** (no runtime services, no “backend/frontend”). It’s a **data/schema artifact repository**: a curated set of **JSON “resource property” schema files** for **AWS Config Configuration Items (CIs)** that are **queryable via the AWS Config `SelectResources` API**.

- **Static artifacts** (the JSON property/type maps)
- **How consumers use them** to build valid `SelectResources` SQL-like queries
- (Optionally) **How maintainers update/publish** the artifacts (GitHub workflow, review, release), even if the CI details aren’t explicit in the file tree.

From the file tree + README, the core structure is:

- `config/properties/resource-types/*.properties.json`
**One file per AWS Config resource type**, named like `AWS::EC2::Instance.properties.json`.
Each file is effectively a **dictionary**: `property.path` → `type` (string/boolean/integer/etc.).

- `config/properties/AWS.properties.json`
A **merged/aggregated** property file containing properties for **all** supported resource types.

- `.github/*`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `LICENSE`, `NOTICE`

This means the “architecture” is fundamentally a **schema distribution + consumption** flow.

##### What the README implies about behavior & interactions
The README defines the consumer workflow:
##### Craft a `SelectResources` query using those property names/types

Also:
- There’s a **supported type system**: `boolean`, `cidr_block`, `date`, `float`, `integer`, `ip`, `string`
- Consumers interact with an external managed service: **AWS Config** (specifically `SelectResources` API)

##### Consumer pulls/reads schema
- `User/Tool` → `GitHub Repo` (clone/download)
- `User/Tool` → `resource-types/*.properties.json` (lookup properties)
- (Alternative path) `User/Tool` → `AWS.properties.json` (global lookup)

##### Consumer authors query
- `Schemas` → `Query Authoring` (property names + types inform query correctness)

##### Query execution
- `User/Tool` → `AWS Config SelectResources API` (submit query)
- `AWS Config` → `Query Results` (resourceIds / counts)

##### Maintenance loop (if diagramming lifecycle)
- `AWS resource type changes / new CI fields` → `Contributors/Maintainers`
- `Maintainers` → `PR to GitHub` → `Schema artifacts updated`

##### Architectural patterns / principles to highlight
This repo follows a **“schema-as-data”** / **reference dataset** pattern:
- **Version-controlled canonical artifacts**
- **Per-entity modularization** (one file per resource type)
- **Aggregation** (single merged file for convenience)
- **Consumer-driven usage** (schemas enable correct API usage; repo itself doesn’t run)

Call out that there is **no runtime coupling** inside the repo—only **data organization** and **consumer workflows**.

##### Technologies / formats to label explicitly
- JSON (`*.properties.json`)
- AWS Config `SelectResources` API (external integration)
- “SQL-like query” (as shown in README examples)
- Type system: boolean/cidr_block/date/float/integer/ip/string

##### What NOT to overcomplicate
- Don’t invent runtime components (servers, queues, DBs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =======================
    %% Diagram 1: System Context (C4-L1)
    %% =======================
    subgraph "System Context (Schema-as-Data Repository)"
        direction TB

        Eng["Engineer (Query Author)"]:::actor
        Auto["Automation (Scripts/Tools)"]:::actor

        Repo["AWS Config Resource Schema (GitHub Repository)"]:::repo
        AwsCfg["AWS Config Service"]:::external
        Sel["SelectResources API (SQL-like Query)"]:::api
        Results["Query Results (resources,counts,resourceIds)"]:::result

        Eng -->|"reads_schema"| Repo
        Auto -->|"reads_schema"| Repo

        Eng -->|"executes_query"| Sel
        Auto -->|"executes_query"| Sel
        Sel -->|"runs_on"| AwsCfg
        AwsCfg -->|"returns_results"| Results
        Results -->|"consumed_by"| Eng
        Results -->|"consumed_by"| Auto

        Repo -->|"informs_query_fields_and_types"| Eng
        Repo -->|"enables_validation/generation"| Auto
    end

    %% =======================
    %% Diagram 2: Artifact / Repo View (C4-L2 adapted)
    %% =======================
    subgraph "Repository Artifacts (Version-Controlled JSON Schemas)"
        direction TB

        Root["Repo Root (artifact store)"]:::repo
        Readme["README (Query Authoring Guidance)"]:::doc

        subgraph "Schema Artifacts (config/properties/)"
            direction TB
            Base["Schema Base Directory"]:::dir

            subgraph "Per-Resource Schemas (resource-types/)"
                direction TB
                RTDir["resource-types/ (one file per AWS Config resource type)"]:::dir
                EC2["AWS::EC2::Instance.properties.json"]:::artifact
                S3["AWS::S3::Bucket.properties.json"]:::artifact
                Etc["Other resource-type schema files (*.properties.json)"]:::artifact
            end

            Merged["AWS.properties.json (Merged: all supported resource types)"]:::artifact
        end

        Root -->|"contains"| Readme
        Root -->|"contains"| Base
        Base -->|"contains"| RTDir
        RTDir -->|"example"| EC2
        RTDir -->|"example"| S3
        RTDir -->|"many"| Etc
        Base -->|"contains"| Merged

        %% Consumption paths
        Eng -->|"lookup_fields"| RTDir
        Eng -->|"optional_bulk_lookup"| Merged
        Auto -->|"bulk_parse"| Merged
        Auto -->|"per_type_parse"| RTDir
        Readme -->|"explains_usage"| Eng
        Readme -->|"guides_tooling"| Auto
    end

    %% =======================
    %% Diagram 3: Schema Semantics / Query Construction
    %% =======================
    subgraph "Schema Semantics → Query Construction"
        direction TB

        FileShape["Resource Property Schema (JSON map)"]:::artifact
        MapShape["Mapping: property.path → type"]:::data
        Types["Supported Types: boolean,cidr_block,date,float,integer,ip,string"]:::types

        Tags["Tag Fields Nuance"]:::note
        TagKV["tags.key + tags.value"]:::data
        TagDerived["derived: tags.tag"]:::data

        Query["SelectResources Query (SQL-like)"]:::query
        Valid["Valid Field Names & Type-Aware Predicates"]:::process

        FileShape -->|"contains"| MapShape
        MapShape -->|"uses"| Types

        Tags -->|"explains"| TagKV
        TagKV -->|"combine_to_form"| TagDerived
        TagDerived -->|"queryable_field"| Query

        MapShape -->|"provides_field_names"| Valid
        Types -->|"constrains_operators"| Valid
        Valid -->|"crafts"| Query
        Query -->|"sent_to"| Sel
    end

    %% =======================
    %% Maintenance / Governance (Optional, from repo signals)
    %% =======================
    subgraph "Maintenance & Governance (Open-Source Workflow)"
        direction TB

        Contrib["Contributors / Maintainers"]:::actor
        PrFlow["Pull Request + Review"]:::process
        PRTemplate["PR Template"]:::doc
        ContribGuide["CONTRIBUTING"]:::doc
        CoC["Code of Conduct"]:::doc
        Lic["LICENSE"]:::doc
        Notice["NOTICE"]:::doc

        Contrib -->|"proposes_changes"| PrFlow
        PrFlow -->|"updates_schema_artifacts"| RTDir
        PrFlow -->|"updates_merged_schema"| Merged

        ContribGuide -->|"defines_process"| PrFlow
        PRTemplate -->|"standardizes_prs"| PrFlow
        CoC -->|"sets_behavior_norms"| Contrib
        Lic -->|"legal_terms"| Root
        Notice -->|"legal_notices"| Root
    end

    %% =======================
    %% Click Events (from component_mapping)
    %% =======================
    click Root "https://github.com/awslabs/aws-config-resource-schema/tree/master/./"
    click Base "https://github.com/awslabs/aws-config-resource-schema/tree/master/config/properties/"
    click RTDir "https://github.com/awslabs/aws-config-resource-schema/tree/master/config/properties/resource-types/"
    click EC2 "https://github.com/awslabs/aws-config-resource-schema/blob/master/config/properties/resource-types/AWS::EC2::Instance.properties.json"
    click S3 "https://github.com/awslabs/aws-config-resource-schema/blob/master/config/properties/resource-types/AWS::S3::Bucket.properties.json"
    click Merged "https://github.com/awslabs/aws-config-resource-schema/blob/master/config/properties/AWS.properties.json"
    click Readme "https://github.com/awslabs/aws-config-resource-schema/blob/master/README.md"
    click ContribGuide "https://github.com/awslabs/aws-config-resource-schema/blob/master/CONTRIBUTING.md"
    click PRTemplate "https://github.com/awslabs/aws-config-resource-schema/blob/master/.github/PULL_REQUEST_TEMPLATE.md"
    click CoC "https://github.com/awslabs/aws-config-resource-schema/blob/master/CODE_OF_CONDUCT.md"
    click Lic "https://github.com/awslabs/aws-config-resource-schema/tree/master/LICENSE"
    click Notice "https://github.com/awslabs/aws-config-resource-schema/tree/master/NOTICE"

    %% =======================
    %% Styles
    %% =======================
    classDef actor fill:#E8F1FF,stroke:#2563EB,stroke-width:1px,color:#0B1B3A
    classDef repo fill:#F3F4F6,stroke:#374151,stroke-width:1px,color:#111827
    classDef dir fill:#FFF7ED,stroke:#C2410C,stroke-width:1px,color:#431407
    classDef artifact fill:#ECFDF5,stroke:#059669,stroke-width:1px,color:#064E3B
    classDef doc fill:#FEFCE8,stroke:#CA8A04,stroke-width:1px,color:#3B2F00
    classDef external fill:#FCE7F3,stroke:#BE185D,stroke-width:1px,color:#4A044E
    classDef api fill:#FFE4E6,stroke:#E11D48,stroke-width:1px,color:#4C0519
    classDef query fill:#E0E7FF,stroke:#4338CA,stroke-width:1px,color:#1E1B4B
    classDef process fill:#EFF6FF,stroke:#0284C7,stroke-width:1px,color:#0C4A6E
    classDef data fill:#F0FDFA,stroke:#0F766E,stroke-width:1px,color:#134E4A
    classDef types fill:#F5F3FF,stroke:#6D28D9,stroke-width:1px,color:#2E1065
    classDef result fill:#DCFCE7,stroke:#16A34A,stroke-width:1px,color:#052E16
    classDef note fill:#FFFBEB,stroke:#D97706,stroke-width:1px,color:#451A03
```
