ara-generate

Generate ARA manifests + schemas from any website. Zero dependencies.

Part of the ARA Standard — Agent-Ready Architecture.

Install & Run

# No install needed — run directly with npx
npx ara-generate https://yoursite.com

# Or install globally
npm install -g ara-generate
ara-generate https://yoursite.com

What it does

The generator analyzes your website and produces:

Layer 1 — Manifest (always generated)

• Extracts identity from <title>, OpenGraph, JSON-LD Organization data
• Detects site type (ecommerce, blog, restaurant, saas, etc.)
• Detects language, contact info, branding
• Analyzes sitemap.xml to detect resource patterns
• Checks for OpenAPI/Swagger endpoints

Layer 2 — Schemas (when structured data is present)

• Converts JSON-LD <script type="application/ld+json"> to ARA schemas
• Converts Microdata (itemscope, itemprop) to ARA schemas
• Generates search_hints (filterable_by, sortable_by, text_searchable)
• Adds semantic annotations (schema:name, schema:price, etc.)

Usage

# Basic: outputs manifest JSON to stdout
npx ara-generate https://yoursite.com

# Save to .well-known/ara/ directory (manifest.json + schemas/)
npx ara-generate https://yoursite.com --output .well-known/ara/

# Layer 1 only (skip schema detection)
npx ara-generate https://yoursite.com --layer 1

# Crawl internal pages to find more structured data
npx ara-generate https://yoursite.com --crawl 10

# Full generation with crawling
npx ara-generate https://yoursite.com --crawl 10 --output .well-known/ara/

When does Layer 2 work?

Layer 2 schemas are auto-generated when your site has structured data:

| Source | Confidence | Example | |--------|-----------|---------| | JSON-LD (<script type="application/ld+json">) | HIGH | Most modern e-commerce, news sites, recipe sites | | Microdata (itemscope, itemprop) | MEDIUM | Older sites, some WordPress themes | | OpenAPI/Swagger | Protocol detection | API-first sites |

Supported Schema.org types

Product, Article, NewsArticle, BlogPosting, Recipe, Event, Restaurant, LocalBusiness, Course

When Layer 2 cannot be auto-generated

• Site has no structured data (plain HTML only) → Layer 1 only, with guidance on what to add
• Content is rendered client-side (SPA without SSR) → Generator sees empty HTML
• Data is behind authentication → Generator can only access public pages

In these cases, the generator produces Layer 1 and prints instructions on how to enable Layer 2.

Output structure

.well-known/ara/
├── manifest.json          ← Always generated
└── schemas/               ← Generated when structured data found
    ├── product.json
    ├── article.json
    └── ...

Example output

  ARA Generator v2.0.0
  Target: https://myshop.com
  Mode: Layer 1 + Layer 2 (schemas)
  ─────────────────────────────────────────

  ✓ Fetched main page (45.2 KB)
  ✓ Extracted metadata: "MyShop"
  ✓ Detected type: ecommerce
  ✓ Found 3 JSON-LD block(s): Product, Organization, BreadcrumbList
  ✓ sitemap.xml (1,250 URLs, 4 pattern(s))

  ── Layer 2: Schema Detection ──────────────────
  ✓ Generated 1 schema(s) from JSON-LD

  ── Results ───────────────────────────────────
  ✓ Generated ARA manifest (Layer 2)
    Identity: MyShop (ecommerce)
    Resources: 5
    Schemas: 1

  ✓ Saved .well-known/ara/manifest.json
  ✓ Saved .well-known/ara/schemas/product.json

Links

• Standard: ara-standard.org
• Specification: GitHub
• Validator: npx ara-validate https://yoursite.com

License

MIT