What Is Machine-Readable Data?
A JSON file at a standardized URL that AI crawlers check automatically. Similar to how robots.txt tells search engines how to crawl your site, brand-facts.json tells AI agents exactly what your business offers. No scraping needed, no HTML parsing, no ambiguity. Just clean structured data.
The file lives at /.well-known/brand-facts.json on your website. The /.well-known/ directory is an established internet standard already used by SSL certificates, security policies, and other machine-readable files. AI agents are increasingly checking this location for structured business data, and early adopters gain a significant advantage as this convention becomes widespread.
Why It Matters
- Speed and accuracy. AI agents can read JSON in milliseconds without parsing HTML. Faster ingestion means higher accuracy and greater confidence in the data. When an AI assistant can pull your pricing, certifications, and product specs from a clean JSON file, it recommends you with more precision.
- Zero ambiguity. JSON is unambiguous.
"founded": 2018 has zero chance of misinterpretation. HTML content can be ambiguous, buried in marketing copy, or mixed with unrelated information. Structured data removes all guesswork.
- Future-proofing. As AI agents get more sophisticated, they increasingly rely on structured data feeds. The shift from scraping HTML to reading structured endpoints is already happening. Implementing this now positions you ahead of the curve.
- Massive differentiator. Less than 1% of businesses serve machine-readable brand data. Having a brand-facts.json file signals to AI systems that you are tech-forward and data-transparent. It is one of the easiest ways to stand out from competitors who have not adopted this standard.
Our Process
- JSON File Creation. We build a comprehensive JSON file following the emerging brand-facts.json standard. This includes your company name, description, products and services, pricing, certifications, contact information, social profiles, and key differentiators. Every data point is verified against your existing web content to ensure accuracy from day one.
- Standard URL Placement. We serve the file at
/.well-known/brand-facts.json, the standardized location that AI agents check automatically. This is similar to how robots.txt works for search engines. AI crawlers know to look here, so your data gets discovered without any additional configuration.
- WordPress Integration. For WordPress sites, we install a lightweight mu-plugin (15 lines of code) that serves the JSON from the standard URL. No bloated plugins, no security risk, no performance impact. The plugin simply routes requests to the correct file. For non-WordPress sites, the JSON file goes directly in your web root directory.
- Data Synchronization. The JSON file mirrors the data on your Brand Facts page and Answer Hub. All three sources stay consistent, which is critical. When AI encounters the same verified facts across multiple formats on your site, it increases confidence in the data and makes recommendations with greater certainty.
- Ongoing Maintenance. When your business data changes, the JSON file updates alongside your web pages. New product added? New certification earned? Price change? One change propagates to all three sources simultaneously. We provide documentation so your team can handle updates independently.
What You Get
- A complete brand-facts.json file with all your verified business data
- Proper deployment at the
/.well-known/ standard URL
- WordPress mu-plugin for automatic serving (if applicable)
- Data synchronized with your Answer Hub and Brand Facts page
- Documentation for your team to update the file when data changes
- Competitive advantage over the 99%+ of businesses that do not serve machine-readable data
Real-World Example
A SaaS company noticed that AI assistants sometimes confused their product features with a competitor's. Both products had similar names. We deployed a brand-facts.json file with precise product descriptions, feature lists, and differentiators. Within 3 weeks, AI responses about both companies became notably more accurate. The JSON file gave AI a definitive, unambiguous data source to reference instead of trying to extract facts from marketing copy.
How This Connects
Machine-Readable Data supplements the human-readable content from Layer 2 (Answer Hub) and Layer 3 (Brand Facts). While those pages serve both humans and AI, the JSON file is purely for machines. The data in the JSON file should exactly mirror what is on those pages, creating redundancy that increases AI confidence. Schema Markup (Layer 5) adds another layer of structured data embedded directly in your HTML.
Previous: Layer 3: Brand Facts Page
Next: Layer 5: Schema Markup Optimization
Frequently Asked Questions
What is a brand-facts.json file?
It is a JSON-formatted file served at /.well-known/brand-facts.json on your website. It contains structured data about your business: name, description, products, pricing, certifications, contact info, and differentiators. AI agents can read it directly without needing to scrape and parse your HTML pages.
Will AI agents actually find and read this file?
AI crawlers are increasingly checking standard data endpoints. The /.well-known/ directory is an established convention (used by SSL certificates, security policies, and other machine-readable files). As AI agent technology matures, structured data feeds at known URLs will become standard. Early adoption positions you ahead of this shift.
Do I need technical skills to implement this?
We handle the full implementation. For WordPress sites, it involves uploading one JSON file and a 15-line PHP plugin. For other platforms, the JSON file goes in your web root directory. We provide documentation so your team can update the file when business data changes.
How is this different from schema markup?
Schema markup is embedded in your HTML pages and describes the content on that specific page. Machine-readable data is a standalone file that provides a complete overview of your business in one place. They serve complementary purposes. Schema helps AI understand individual pages, while brand-facts.json gives AI a comprehensive company overview.
What happens if my JSON data conflicts with my website content?
Data consistency is critical. If your JSON says one price and your website says another, AI may lower its confidence in both sources. We synchronize the JSON file with your Answer Hub and Brand Facts page to ensure all sources match. Our update process changes all three simultaneously.