# yext/openapi architecture

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

- Interactive diagram: https://gitdiagram.com/yext/openapi
- Repository: https://github.com/yext/openapi

## Overview

##### Project type and purpose
- This repository is an “OpenAPI specification” library for the Yext API.
- It is not a running application but a collection of machine-readable API definitions in both JSON and YAML formats.
- Its purpose is to define, validate, generate code for, and publish the API surface of the Yext platform.

##### File structure
- Top-level:
- .github/workflows/main.yml – CI pipeline
- LICENSE, README.md
- json/ – each file is a complete OpenAPI JSON spec for one API segment
- yaml/ – the same specs in YAML format
- There are no “src” or “bin” folders because this is a spec-only project.
- CI config implies linting, formatting, generation, and/or publication steps.

##### README
- Single line: “OpenAPI specification for the Yext API.”

##### Main components
a. Spec repository (GitHub)
- Directory of JSON and YAML definitions
- Version control (Git)
b. Continuous Integration (GitHub Actions)
- Lint/validate step (e.g., Spectral or Swagger CLI)
- Round-trip conversion between JSON and YAML, if used
- Code generation step (e.g., openapi-generator)
- Documentation generation (e.g., Redoc, Swagger UI)
- Publication/deployment (e.g., push docs to static site or API portal)
c. Output artifacts
- Generated client/server SDKs
- Rendered API documentation
d. External consumers
- Developers (who consume docs or SDKs)
- Downstream services that will integrate with the Yext API
- Hosting environment for docs (e.g., GitHub Pages, CDN)

##### Relationships and interactions
- A developer pushes changes to the JSON or YAML folder →
- GitHub Actions triggers →
- Step 1: Validate all specs
- Step 2: (Optionally) convert/ensure sync between JSON and YAML
- Step 3: Generate SDKs or schemas
- Step 4: Build static documentation site
- Step 5: Deploy docs and artifacts to a hosting target or package registry
- Consumers fetch SDK packages or browse the published docs

##### Architectural patterns and principles
- Single source of truth: the OpenAPI files in YAML and JSON
- CI/CD pipeline that enforces quality, generates code and docs automatically
- Separation of concerns: specs (input) vs. processes (CI tasks) vs. outputs (artifacts)
- Idempotent builds: pipeline always recreates artifacts from specs

##### Additional guidance
- Major interactions (e.g., “push to repo triggers workflow,” “artifact uploaded to CDN”)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Spec Repository
  subgraph "Spec Repository (Source of Truth)"
    dirJSON[/json/]:::source
    dirYAML[/yaml/]:::source
    README["README.md"]:::source
    LICENSE["LICENSE"]:::source
    dirJSON --> jsonAdmin["adminapi.json"]:::source
    dirJSON --> jsonAnswers["answersapi.json"]:::source
    dirJSON --> jsonChat["chatapi.json"]:::source
    dirJSON --> jsonEvents["eventsapi.json"]:::source
    dirJSON --> jsonKnowledge["knowledgeapi.json"]:::source
    dirJSON --> jsonLive["liveapi.json"]:::source
    dirJSON --> jsonPublisherECL["publishereclapi.json"]:::source
    dirJSON --> jsonPublisherListings["publisherlistingsapi.json"]:::source
    dirJSON --> jsonPublisherNotify["publishernotifyreviewapi.json"]:::source
    dirJSON --> jsonPublisherTracking["publishertrackingpixelapi.json"]:::source
    dirJSON --> jsonWebhooks["webhooks.json"]:::source
    dirYAML --> yamlAdmin["adminapi.yaml"]:::source
    dirYAML --> yamlAnswers["answersapi.yaml"]:::source
    dirYAML --> yamlChat["chatapi.yaml"]:::source
    dirYAML --> yamlEvents["eventsapi.yaml"]:::source
    dirYAML --> yamlKnowledge["knowledgeapi.yaml"]:::source
    dirYAML --> yamlLive["liveapi.yaml"]:::source
    dirYAML --> yamlPublisherECL["publishereclapi.yaml"]:::source
    dirYAML --> yamlPublisherListings["publisherlistingsapi.yaml"]:::source
    dirYAML --> yamlPublisherNotify["publishernotifyreviewapi.yaml"]:::source
    dirYAML --> yamlPublisherTracking["publishertrackingpixelapi.yaml"]:::source
    dirYAML --> yamlWebhooks["webhooks.yaml"]:::source
  end

  developer["Developer Push"]:::external
  developer -->|push to repo triggers| dirJSON
  developer --> dirYAML

  %% CI Configuration
  CICfg["CI Config"]:::source
  developer --> CICfg
  CICfg -->|"uses .github/workflows/main.yml"| LintValidate

  subgraph "CI Pipeline"
    LintValidate["1. Lint & Validate Specs"]:::process
    ConvertSync["2. Convert & Sync JSON/YAML"]:::process
    GenerateSDKs["3. Generate SDKs"]:::process
    BuildDocs["4. Build Documentation Site"]:::process
    Deploy["5. Deploy Artifacts"]:::process
  end

  LintValidate --> ConvertSync --> GenerateSDKs --> BuildDocs --> Deploy

  %% Outputs
  subgraph "Output Artifacts"
    SDKs["Generated SDKs"]:::artifact
    Docs["Rendered API Documentation"]:::artifact
  end
  Deploy --> SDKs
  Deploy --> Docs

  %% Hosting and Consumers
  hosting["Hosting Environment\n(GitHub Pages/CDN)"]:::external
  Deploy -->|upload docs| hosting
  SDKs -->|publish to registry| hosting

  developers["External Developers"]:::external
  services["Downstream Services"]:::external

  developers -->|consume docs| Docs
  developers -->|install SDKs| SDKs
  services -->|integrate via SDKs| SDKs

  %% Click Events
  click dirJSON "https://github.com/yext/openapi/tree/main/json/"
  click dirYAML "https://github.com/yext/openapi/tree/main/yaml/"
  click jsonAdmin "https://github.com/yext/openapi/blob/main/json/adminapi.json"
  click jsonAnswers "https://github.com/yext/openapi/blob/main/json/answersapi.json"
  click jsonChat "https://github.com/yext/openapi/blob/main/json/chatapi.json"
  click jsonEvents "https://github.com/yext/openapi/blob/main/json/eventsapi.json"
  click jsonKnowledge "https://github.com/yext/openapi/blob/main/json/knowledgeapi.json"
  click jsonLive "https://github.com/yext/openapi/blob/main/json/liveapi.json"
  click jsonPublisherECL "https://github.com/yext/openapi/blob/main/json/publishereclapi.json"
  click jsonPublisherListings "https://github.com/yext/openapi/blob/main/json/publisherlistingsapi.json"
  click jsonPublisherNotify "https://github.com/yext/openapi/blob/main/json/publishernotifyreviewapi.json"
  click jsonPublisherTracking "https://github.com/yext/openapi/blob/main/json/publishertrackingpixelapi.json"
  click jsonWebhooks "https://github.com/yext/openapi/blob/main/json/webhooks.json"
  click yamlAdmin "https://github.com/yext/openapi/blob/main/yaml/adminapi.yaml"
  click yamlAnswers "https://github.com/yext/openapi/blob/main/yaml/answersapi.yaml"
  click yamlChat "https://github.com/yext/openapi/blob/main/yaml/chatapi.yaml"
  click yamlEvents "https://github.com/yext/openapi/blob/main/yaml/eventsapi.yaml"
  click yamlKnowledge "https://github.com/yext/openapi/blob/main/yaml/knowledgeapi.yaml"
  click yamlLive "https://github.com/yext/openapi/blob/main/yaml/liveapi.yaml"
  click yamlPublisherECL "https://github.com/yext/openapi/blob/main/yaml/publishereclapi.yaml"
  click yamlPublisherListings "https://github.com/yext/openapi/blob/main/yaml/publisherlistingsapi.yaml"
  click yamlPublisherNotify "https://github.com/yext/openapi/blob/main/yaml/publishernotifyreviewapi.yaml"
  click yamlPublisherTracking "https://github.com/yext/openapi/blob/main/yaml/publishertrackingpixelapi.yaml"
  click yamlWebhooks "https://github.com/yext/openapi/blob/main/yaml/webhooks.yaml"
  click README "https://github.com/yext/openapi/blob/main/README.md"
  click LICENSE "https://github.com/yext/openapi/tree/main/LICENSE"
  click CICfg "https://github.com/yext/openapi/blob/main/.github/workflows/main.yml"

  %% Styles
  classDef source fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
  classDef process fill:#DFF5D8,stroke:#2F8F2F,color:#2F8F2F;
  classDef artifact fill:#FFE8C2,stroke:#D99000,color:#D99000;
  classDef external fill:#F0F0F0,stroke:#999999,color:#555555,stroke-dasharray: 5 5;
  class dirJSON,dirYAML,README,LICENSE source
  class LintValidate,ConvertSync,GenerateSDKs,BuildDocs,Deploy process
  class SDKs,Docs artifact
  class developer,developers,services,hosting external
```
