# tmforum-apis/open_api_and_data_model architecture

> Architecture diagram of the GitHub repository tmforum-apis/open_api_and_data_model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tmforum-apis/open_api_and_data_model
- Repository: https://github.com/tmforum-apis/open_api_and_data_model

## Overview

##### Project type and purpose
- This is not a traditional source-code project but rather a TM Forum Open API and datamodel “specification repository.”
- It contains hundreds of TMF APIs in OpenAPI/Swagger format plus a comprehensive JSON-Schema datamodel under **schemas/**.

##### File structure
- Top-level directories:
– **apis/**: One folder per TMF API (TMF621, TMF622, …). Each subfolder has:
· **/swaggers**: OpenAPI/Swagger JSON files (v4.0.0, v4.1.0, etc.)
· **/samples**: JSON examples of requests/responses
– **schemas/**: Categorized JSON Schema definitions subdivided by domain (Common, Customer, Product, Resource, Service, IoT, Analytics, etc.).
– **README.md**: High-level statement (“TM Forum Open API and Datamodel”).

##### README
- Minimal content: confirms this is the TM Forum Open API + datamodel repository.
- No runnable code; primary assets are contracts (schemas) and API specs.

a. Components
1. Git Monorepo (root): version control of all API specs and schemas.
2. CI/CD Pipeline:
– Linter/Validator for OpenAPI files
– JSON-Schema validator for schemas
– Static site/build (e.g. Swagger-UI, Redoc, or Hugo)
3. Artifact Registry:
– Published Swagger JSON (npm package, Maven artifact, GitHub Release)
– Published JSON Schema bundle
4. Documentation Portal (Docs Site):
– Renders interactive API docs (Swagger UI/Redoc instances per API)
– Schema browser (e.g. JSON Schema View)
– Samples explorer
5. Downstream Consumers:
– SDK generators (e.g. OpenAPI Generator)
– Code-gen pipelines
– Integrations (e.g. API gateways, mock servers)

b. Relationships & data flows
- Developer pushes changes to Git → triggers CI/CD
- CI/CD validates specs & schemas → on success publishes artifacts
- Static site generator pulls published artifacts → updates docs site
- Consumers (developers, partners) access docs site or pull artifacts for codegen.

c. Architectural patterns/design principles
- Monorepo pattern: all APIs and schemas versioned together
- Separation of concerns:
– Storage (Git)
– Validation (CI)
– Publication (Artifact registry)
– Presentation (Docs portal)
- Declarative contracts: OpenAPI for endpoints, JSON Schema for data model
- Single source of truth for models (no duplication)—all directory-based.

d. Key technologies/frameworks
- Git/GitHub (monorepo hosting)
- CI/CD (Jenkins/GitHub Actions/Travis)
- OpenAPI Linter (Spectral)
- JSON Schema Validator (ajv)
- Static site generator (Redocly, Swagger UI, Docusaurus, Hugo)
- Artifact registry (GitHub Releases, npm, Maven)

##### Detail level
- Every stage (lint → validate → generate → publish).
- Both OpenAPI and JSON-Schema pipelines if separate.
- Traceability: Git folder → specific API folder → swagger file → generated docs page.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Storage
    subgraph "Git Monorepo (Source Repository)" 
        GitRepo["Git Monorepo"]:::storage
        ApiSpecs["API Specifications"]:::storage
        Samples["Sample Payloads"]:::storage
        Diagrams["UML/Diagram Artifacts"]:::storage
        Schemas["JSON-Schema Data Model"]:::storage
        Common["Common Domain Schemas"]:::storage
        Customer["Customer Domain Schemas"]:::storage
        Product["Product Domain Schemas"]:::storage
        Resource["Resource Domain Schemas"]:::storage
        Service["Service Domain Schemas"]:::storage
        Analytics["Analytics Domain Schemas"]:::storage
        IoT["IoT Domain Schemas"]:::storage
    end

    %% CI Pipeline
    subgraph "CI/CD Pipeline" 
        Lint["OpenAPI Linter (Spectral)"]:::process
        Validate["JSON-Schema Validator (ajv)"]:::process
        DiagGen["Diagram Generator"]:::process
        SiteBuild["Static Site Generator"]:::process
    end

    %% Artifact Registry
    Artifact["Artifact Registry"]:::storage

    %% Documentation Portal
    subgraph "Documentation Portal" 
        DocsUI["Interactive API Docs"]:::presentation
        SchemaBrowser["Schema Browser"]:::presentation
        SamplesExplorer["Samples Explorer"]:::presentation
    end

    %% Consumers
    subgraph "Downstream Consumers" 
        SDKGen["SDK Generators"]:::consumer
        Integrations["Integrations & Mock Servers"]:::consumer
    end

    %% Flows
    GitRepo -->|push changes| Lint
    GitRepo -->|push changes| Validate
    GitRepo -->|push changes| DiagGen
    GitRepo -->|push changes| SiteBuild

    Lint -->|lint & report| Validate
    Validate -->|validate & approve| DiagGen
    DiagGen -->|generate diagrams| SiteBuild
    SiteBuild -->|build site| Artifact

    Artifact -->|publish specs & schemas| DocsUI
    Artifact -->|publish specs & schemas| SchemaBrowser
    Artifact -->|publish specs & schemas| SamplesExplorer

    DocsUI -->|access docs| SDKGen
    DocsUI -->|access docs| Integrations
    SchemaBrowser -->|browse schemas| SDKGen
    SamplesExplorer -->|view samples| Integrations

    %% Click Events
    click GitRepo "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//"
    click ApiSpecs "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//apis/"
    click Samples "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//apis/"
    click Diagrams "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//apis/TMF621_Trouble_Ticket/documentation/diagrams"
    click Schemas "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/"
    click Common "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/Common/"
    click Customer "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/Customer/"
    click Product "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/Product/"
    click Resource "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/Resource/"
    click Service "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/Service/"
    click Analytics "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/Analytics/"
    click IoT "https://github.com/tmforum-apis/open_api_and_data_model/tree/master//schemas/Iot/"

    %% Styles
    classDef storage fill:#bbdefb,stroke:#1976d2,color:#0d47a1
    classDef process fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef presentation fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef consumer fill:#e1bee7,stroke:#8e24aa,color:#4a148c
```
