Skip to content

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: 
    {
  "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