---
canonical: https://docs.jentic.com/reference/public-apis/oak-structure/
representation: markdown-alternate
# Canonical page: https://docs.jentic.com/reference/public-apis/oak-structure/
# This is the Markdown alternate of the page above.
description: >-
  Understand the Open Agentic Knowledge (OAK) repository structure that Jentic Public
  APIs follows, giving API descriptions and workflows a predictable layout.
---

# OAK Repository Structure

The **Open Agentic Knowledge (OAK)** standard defines a predictable layout for API descriptions (e.g., OpenAPI) and workflows.
Jentic Public APIs follows this structure to make content easy to find, validate, and index.

---

## Top‑level layout

```
**data**/
├─ apis/
│  └─ openapi/
│     └─ <vendor>/
│        ├─ main/ | <api-name>/
│        │  ├─ meta.json
│        │  └─ <version>/
│        │     ├─ openapi.json        # standardized spec
│        │     └─ orig/spec.yaml      # original source
└─ workflows/
├─ <vendor>.com/
│  ├─ workflows.arazzo.json
│  └─ payment-flows.arazzo.json
├─ <vendor>.com\~<api>/
│  └─ workflows.arazzo.json
└─ <vendorA>.com+<vendorB>.com\~<api>/
└─ workflows.arazzo.json

```

> Note: Correct extension is **`.arazzo.json`** (not `arrazo`).

---

## API Descriptions or Documents (OpenAPI)

- Organized by **vendor** then **API** (single‑API vendors use `main/`)
- **Versioned** under `info.version`
- Each version keeps:
  - `openapi.json` — normalized spec (with `info.x-jentic-source-url`)
  - `orig/spec.*` — original downloaded source for traceability
- `meta.json` contains OAK metadata:
  ```json
  {
    "oak_meta": "1.0.0",
    "api_info": {
      "id": "md5hash",
      "format": "openapi",
      "vendor": "vendor",
      "api_name": "api_name",
      "friendly_id": "vendor"  // or "vendor/api_name"
    }
  }
  ```

---

## Workflows (Arazzo)

* **Single API**: `<vendor>.com/` or `<vendor>.com~<api>/`
* **Multi‑API**: `<vendorA>.com+<vendorB>.com~<api>/` (alphabetical)

Files:

* `workflows.arazzo.json` — default
* Additional purpose‑specific files, e.g.:

  * `payment-flows.arazzo.json`
  * `auth-flows.arazzo.json`
  * `integration-flows.arazzo.json`

---

## Why OAK?

* Consistent layout for **indexing & automation**
* Easier **contribution & validation**
* Durable foundation for **agent execution** and **tool generation**