Mirror Adoption
A Machine Mirror is a structured, machine-readable layer you publish at /.well-known/aiep/ on your domain. It makes your knowledge artefacts discoverable and retrievable by AI systems configured to walk AIEP endpoints.
This page answers the question: should I adopt the Mirror pattern, and where do I begin?
For the full technical implementation, see Mirror: Implement.
Should I adopt a Mirror?
| Scenario | Adopt a Mirror? | Reason |
|---|---|---|
| You publish research, data, or documentation that AI systems should be able to find | Yes | Without a Mirror, AI retrieval systems cannot discover your artefacts |
| You want your evidence-backed claims to be verifiable by third parties | Yes | The Mirror is the publication surface for schema-conformant artefacts |
| You are building an AI system that retrieves from the open web | Yes | You should implement the retrieval side of the protocol |
| You are a regulated entity publishing compliance artefacts | Yes | A Mirror is required for AIEP certification and conjunction trust |
| You only consume AIEP artefacts and don’t publish | Not required | But you should check for /.well-known/aiep/ when accessing knowledge publishers |
| You are building an internal tool with no public knowledge outputs | Optional | Internal Mirrors are supported but not required |
The Mirror endpoint structure
| Endpoint | Required | Purpose |
|---|---|---|
/.well-known/aiep/index.json | Yes | Lists all artefact paths relative to the Mirror root |
/.well-known/aiep/metadata.json | Yes | Publisher identity: issuer_did, schema_version, last_updated, artefact_count |
/.well-known/aiep/artefacts/*.json | Yes | The artefacts themselves — one file per artefact, schema-conformant |
/.well-known/aiep/certificate.json | If certified | Certificate artefact with cert_id, cert_hash, policy_ref, expires |
/.well-known/aiep/dissent/*.json | If using dissent archive | Archived outlier claims with evidence references intact |
What a retriever does with your Mirror
When an AI retrieval system encounters your domain:
- Checks for
/.well-known/aiep/index.json— if absent, no AIEP discovery - Reads
metadata.json— establishes publisher identity and schema version - Fetches artefact paths from
index.json - For each artefact: validates schema conformance, checks
artefact_hash, checksevidence_refs - If
certification.claimis present: resolvesissuer_didfrom registry and verifiescert_hash - Admits artefact into retrieval results if all checks pass, or logs failure if fail-closed flag is set
Adoption steps
| Step | What to do | Time estimate |
|---|---|---|
| 1 | Create /.well-known/aiep/ directory on your server or static host | Minutes |
| 2 | Publish metadata.json with your issuer_did (can be provisional) and schema version | Minutes |
| 3 | Publish one or more artefacts conforming to a canonical schema | Hours to days |
| 4 | Publish index.json listing all artefact paths | Minutes |
| 5 | Validate using the AIEP Validator | Minutes |
| 6 | (Optional) Submit issuer DID for registry listing to enable certification | Days |
Related
- Mirror: Implement — full technical specification for Mirror setup
- Quickstart — minimal working Mirror in minutes
- Schema Catalogue — the 13 canonical schemas
- Validator — check your Mirror is valid
- Adoption levels — what you gain at each level of adoption