How tmforum-apis/open_api_and_data_model works
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.