{"id":50454180,"url":"https://github.com/mizcausevic-dev/ai-evidence-format-spec","last_synced_at":"2026-06-01T01:05:43.694Z","repository":{"id":357283919,"uuid":"1236253619","full_name":"mizcausevic-dev/ai-evidence-format-spec","owner":"mizcausevic-dev","description":"AI Evidence Format v0.1 draft. JSON document format for structured citations that travel with LLM-generated claims: source identity, span selector, retrieval confidence, freshness, content hash, declared synthesis role. Part of the Kinetic Gain Protocol Suite.","archived":false,"fork":false,"pushed_at":"2026-05-12T04:53:00.000Z","size":21,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T06:34:24.175Z","etag":null,"topics":["ai-citations","ai-governance","answer-engine","evidence","json-schema","kinetic-gain-protocol-suite","llm","platform-engineering","protocol","provenance","rag","specification"],"latest_commit_sha":null,"homepage":"https://github.com/mizcausevic-dev/ai-evidence-format-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:49:50.000Z","updated_at":"2026-05-12T04:53:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mizcausevic-dev/ai-evidence-format-spec","commit_stats":null,"previous_names":["mizcausevic-dev/ai-evidence-format-spec"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mizcausevic-dev/ai-evidence-format-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fai-evidence-format-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fai-evidence-format-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fai-evidence-format-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fai-evidence-format-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mizcausevic-dev","download_url":"https://codeload.github.com/mizcausevic-dev/ai-evidence-format-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fai-evidence-format-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":["ai-citations","ai-governance","answer-engine","evidence","json-schema","kinetic-gain-protocol-suite","llm","platform-engineering","protocol","provenance","rag","specification"],"created_at":"2026-06-01T01:05:43.616Z","updated_at":"2026-06-01T01:05:43.688Z","avatar_url":"https://github.com/mizcausevic-dev.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Evidence Format\n\n[![Validate examples](https://github.com/mizcausevic-dev/ai-evidence-format-spec/actions/workflows/validate.yml/badge.svg)](https://github.com/mizcausevic-dev/ai-evidence-format-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 **machine-readable evidence objects** that travel with every claim an answer engine produces.\n\nWhen an LLM says *\"Cambridge is in Massachusetts, source: en.wikipedia.org/wiki/Cambridge,_Massachusetts\"*, the answer is two things: the **claim** and the **evidence**. Today the evidence is unstructured — a URL, maybe a quoted span, maybe nothing. The AI Evidence Format makes it structured: source identity, span selector, retrieval confidence, freshness, content hash, and a declared synthesis role.\n\n## The three pillars\n\n| Pillar | What it does |\n|---|---|\n| **Attach** | Every cited claim carries one or more evidence objects in a defined format |\n| **Verify** | Each evidence object carries a content hash (and optional signature) so consumers can detect tampering or staleness |\n| **Synthesize** | Each object declares its role in the answer — `supporting`, `contradicting`, `partial`, `background` — making \"the model cited two sources that disagree\" a first-class fact |\n\n## Why not just a URL?\n\nA URL in a footnote tells you where to look. It does not tell you:\n- **Which span** of the source was used (the page is 12,000 words; which sentence?)\n- **How confident** the retrieval system was that this was relevant\n- **How fresh** the content was when retrieved\n- **Whether the content hash matches** what the model actually consumed (the page may have changed)\n- **What role** the evidence played — did the model use it to support, contradict, or only as background?\n\nThe AI Evidence Format makes each of those answerable in a single JSON object.\n\n## Why not Schema.org `Citation` or W3C Annotations?\n\nThose vocabularies describe citations as documents. The AI Evidence Format describes citations as *retrieval artifacts in a generative pipeline*. The differences:\n\n- We need retrieval method and confidence (vector / keyword / graph / hybrid)\n- We need freshness at the moment of retrieval (not document publication date)\n- We need synthesis role (the model's *intended use* of the evidence)\n- We need a content hash that lets a consumer verify the model read what it claims to have read\n\nThe format **reuses** Schema.org wherever it fits, but it is not a subset of any existing vocabulary.\n\n## Quickstart\n\n1. For each claim your answer engine produces, build one or more evidence objects conforming to [`evidence.schema.json`](evidence.schema.json).\n2. Compute a `content_hash` over the canonicalized bytes of the cited span. (See §5 of [`SPEC.md`](SPEC.md) for the canonicalization rules.)\n3. Either embed the evidence inline in your answer payload, or publish it at a URI and reference it.\n4. Pair with an [AEO Protocol](https://github.com/mizcausevic-dev/aeo-protocol-spec) declaration on the source origin to give consumers an authoritative anchor.\n\n## Files in this repo\n\n- [`SPEC.md`](SPEC.md) — full v0.1 specification\n- [`evidence.schema.json`](evidence.schema.json) — JSON Schema (draft 2020-12)\n- [`examples/`](examples/) — reference documents for a supporting citation, a contradicting citation, and a background-only citation\n\n## Status\n\n**v0.1 draft.** Issues and pull requests welcome.\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## 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%2Fai-evidence-format-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmizcausevic-dev%2Fai-evidence-format-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizcausevic-dev%2Fai-evidence-format-spec/lists"}