{"id":50454186,"url":"https://github.com/mizcausevic-dev/aeo-protocol-spec","last_synced_at":"2026-06-01T01:05:49.137Z","repository":{"id":357279438,"uuid":"1236227638","full_name":"mizcausevic-dev/aeo-protocol-spec","owner":"mizcausevic-dev","description":"AEO Protocol v0.1 draft. A well-known JSON document at /.well-known/aeo.json that lets entities declare authoritative claims, citation preferences, and audit hooks for answer engines. Spec + JSON Schema + Person/Organization/Product examples.","archived":false,"fork":false,"pushed_at":"2026-05-12T05:23:56.000Z","size":265,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T06:23:31.135Z","etag":null,"topics":["aeo","ai-governance","answer-engine-optimization","entity-graph","generative-engine-optimization","json-ld","json-schema","kinetic-gain-protocol-suite","llm","platform-engineering","protocol","schema-org","semantic-web","specification","well-known"],"latest_commit_sha":null,"homepage":"https://github.com/mizcausevic-dev/aeo-protocol-spec","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mizcausevic-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-12T04:05:16.000Z","updated_at":"2026-05-12T05:23:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mizcausevic-dev/aeo-protocol-spec","commit_stats":null,"previous_names":["mizcausevic-dev/aeo-protocol-spec"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mizcausevic-dev/aeo-protocol-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Faeo-protocol-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Faeo-protocol-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Faeo-protocol-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Faeo-protocol-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mizcausevic-dev","download_url":"https://codeload.github.com/mizcausevic-dev/aeo-protocol-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Faeo-protocol-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33755379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aeo","ai-governance","answer-engine-optimization","entity-graph","generative-engine-optimization","json-ld","json-schema","kinetic-gain-protocol-suite","llm","platform-engineering","protocol","schema-org","semantic-web","specification","well-known"],"created_at":"2026-06-01T01:05:44.093Z","updated_at":"2026-06-01T01:05:44.162Z","avatar_url":"https://github.com/mizcausevic-dev.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# AEO Protocol\n\n[![Validate examples](https://github.com/mizcausevic-dev/aeo-protocol-spec/actions/workflows/validate.yml/badge.svg)](https://github.com/mizcausevic-dev/aeo-protocol-spec/actions/workflows/validate.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nA draft specification for making entity declarations **machine-readable, discoverable, and auditable** by answer engines.\n\n![AEO Visualizer — Explore view](docs/screenshots/01-explore.png)\n\n\u003e Above: the [AEO Protocol Visualizer](https://ai.studio/apps/27c8e83e-765f-4221-8238-a61df1f3e233) rendering the reference Person declaration at [mizcausevic-dev.github.io/.well-known/aeo.json](https://mizcausevic-dev.github.io/.well-known/aeo.json) — entity card, primary sources, verifications, and six authoritative claims.\n\nThe SEO era assumed humans typed queries into a search box and clicked blue links. The answer-engine era assumes an LLM composes a synthesized response in which a brand, person, product, or place may be cited, paraphrased, or omitted. AEO is the layer that lets an entity declare *what is authoritative about it*, *where to find that declaration*, and *how to verify it was used correctly*.\n\nThis repo is the v0.1 draft of the protocol, the JSON Schema that validates a conforming document, and three reference examples.\n\n## The three pillars\n\n| Pillar | What it does | File on your origin |\n|---|---|---|\n| **Declare** | One JSON document describing the entity, its authoritative claims, and citation preferences | `/.well-known/aeo.json` |\n| **Discover** | A fixed well-known URL so any answer engine can find the declaration without bespoke crawling | Same path on every origin |\n| **Audit** | A signed or queryable surface that lets a publisher verify which claims were cited in a given answer | Optional endpoint in the document |\n\n![AEO Visualizer — Three Pillars](docs/screenshots/02-about.png)\n\n## Why not just JSON-LD / Schema.org?\n\nSchema.org tells an answer engine *what is true about this page*. It does not tell the engine:\n\n- **Which sources are canonical vs. stale** for a given entity\n- **How the publisher wants to be attributed**\n- **What freshness window applies to each claim**\n- **Which claims must / must not appear in a synthesized answer**\n- **How to verify the publisher endorsed the declaration**\n\nAEO is built on top of JSON-LD vocabulary where useful (`schema.org` predicates are first-class), but it adds the **citation, freshness, and audit** semantics that synthesized-answer surfaces actually need.\n\n## Why not llms.txt / ai.txt / robots.txt?\n\n- **`robots.txt`** controls *crawling*. AEO controls *citation and synthesis*.\n- **`llms.txt`** ([answer.ai proposal](https://llmstxt.org/)) tells an LLM *what content to read*. AEO tells it *what to consider authoritative and how to cite it*.\n- **`ai.txt`** ([Spawning proposal](https://site.spawning.ai/spawning-ai-txt)) is opt-out signaling for training data. AEO is opt-in declaration for inference-time citation.\n\nAEO is complementary to all three. A publisher should serve `robots.txt`, optionally serve `llms.txt`, and additionally serve `/.well-known/aeo.json` for citation-grade declarations.\n\n## Quickstart\n\n1. Write an `aeo.json` document conforming to [`aeo.schema.json`](aeo.schema.json). Start from one of the [examples](examples/).\n2. Validate it with any JSON Schema 2020-12 validator (e.g. `ajv`, `jsonschema`).\n3. Serve it at `https://your-origin/.well-known/aeo.json`. Use `Content-Type: application/aeo+json` if your host permits MIME override; `application/json` is also conforming.\n4. (Optional, conformance Level 2+) Add a verification record — a DNS TXT entry or signed JWK — referenced from the document.\n5. (Optional, conformance Level 3) Expose an audit endpoint so consumers can post back which claims they cited.\n\n![AEO Visualizer — JSON Editor](docs/screenshots/03-editor.png)\n\n\u003e The visualizer's JSON Editor view: paste any conforming `aeo.json` and see it render as an entity card with claims, authority, and citation preferences. Useful for authoring and debugging declarations before deploying.\n\n## Files in this repo\n\n- [`SPEC.md`](SPEC.md) — full v0.1 specification\n- [`aeo.schema.json`](aeo.schema.json) — JSON Schema (draft 2020-12) for validation\n- [`examples/aeo-person.json`](examples/aeo-person.json) — reference document for a Person entity\n- [`examples/aeo-organization.json`](examples/aeo-organization.json) — reference document for an Organization entity\n- [`examples/aeo-product.json`](examples/aeo-product.json) — reference document for a Product entity\n\n## Reference implementations\n\nWorking, tested, CI-gated implementations of this specification:\n\n| Repo | Stack | What it does |\n|---|---|---|\n| [aeo-sdk-python](https://github.com/mizcausevic-dev/aeo-sdk-python) | Python · pydantic v2 · httpx | Parse, build, validate, fetch. Sync and async. 8 tests. |\n| [aeo-sdk-typescript](https://github.com/mizcausevic-dev/aeo-sdk-typescript) | TypeScript · zod · native fetch | Parse, build, validate, fetch. ESM-only, Node 18+. 10 tests. |\n| [aeo-sdk-rust](https://github.com/mizcausevic-dev/aeo-sdk-rust) | Rust · serde · ureq (optional) | Parse, build, validate, fetch. Strict `deny_unknown_fields`. 7 tests. |\n| [aeo-sdk-go](https://github.com/mizcausevic-dev/aeo-sdk-go) | Go · stdlib only | Parse, build, validate, fetch. Zero non-stdlib deps. 10 tests. |\n| [aeo-cli](https://github.com/mizcausevic-dev/aeo-cli) | Rust · clap | `aeo validate`, `aeo fetch`, `aeo inspect`, `aeo claim`. Colored output. |\n| [aeo-crawler](https://github.com/mizcausevic-dev/aeo-crawler) | Go · stdlib | BFS crawler — follows `primary_sources` to build an AEO declaration graph. Emits JSON Lines. |\n\nAll implementations load and validate against the canonical [examples](examples/) in this repository.\n\n## Status\n\n**v0.1 draft.** Not ratified by any standards body. Authored as an opinionated starting point for the post-search era. Issues and pull requests welcome; substantive proposals should reference the conformance level they affect.\n\n## License\n\nMIT-licensed. The specification text, JSON Schema, and example documents in this repository may be freely implemented, extended, redistributed, or incorporated into commercial or non-commercial products with attribution. Reference implementations of this spec (such as [mcp-kinetic-gain](https://github.com/mizcausevic-dev/mcp-kinetic-gain)) are licensed separately under AGPL-3.0.\n\n## Working interest\n\nThis protocol is part of a wider platform-engineering effort to give brands, products, and people first-class standing in the answer-engine era. Related work lives under the same author: [github.com/mizcausevic-dev](https://github.com/mizcausevic-dev).\n\n## Kinetic Gain Protocol Suite\n\nA family of open specifications for the answer-engine era. Each spec is a self-contained JSON document format with its own JSON Schema and reference examples; together they compose into an end-to-end account of entity, agent, prompt, tool, and citation.\n\n| Spec | What it does |\n|---|---|\n| **[AEO Protocol](https://github.com/mizcausevic-dev/aeo-protocol-spec)** | Entity declaration at `/.well-known/aeo.json` — authoritative claims, citation preferences, audit hooks |\n| [Prompt Provenance](https://github.com/mizcausevic-dev/prompt-provenance-spec) | Versioned, lineaged, reviewable LLM prompt records |\n| [Agent Cards](https://github.com/mizcausevic-dev/agent-cards-spec) | Declarative agent capability and refusal disclosure |\n| [AI Evidence Format](https://github.com/mizcausevic-dev/ai-evidence-format-spec) | Structured citations that travel with LLM-generated claims |\n| [MCP Tool Cards](https://github.com/mizcausevic-dev/mcp-tool-card-spec) | Per-tool disclosure layered on Model Context Protocol servers |\n\n---\n\n**Connect:** [LinkedIn](https://www.linkedin.com/in/mirzacausevic/) · [Kinetic Gain](https://kineticgain.com) · [Medium](https://medium.com/@mizcausevic/) · [Skills](https://mizcausevic.com/skills/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizcausevic-dev%2Faeo-protocol-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmizcausevic-dev%2Faeo-protocol-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizcausevic-dev%2Faeo-protocol-spec/lists"}