Documentation
aiseo-audit JSON report schema for scores and factors
In brief. This is the aiseo-audit JSON report schema for the overall score, grade, pipeline stages, categories, factors, evidence tiers, recommendations, raw measurements, and version fields returned by a page audit.
Maintained by Jeff Patterson and Agency Enterprise · Updated August 30, 2026
How the aiseo-audit JSON report schema works: overview
The top level identifies the page and overall result. Nested stages, categories, and factors preserve the measurements and evidence behind that result.
The structure keeps the score traceable because every recommendation points back to a measured factor. This means a consumer can display a short summary without discarding the underlying record.
aiseo-audit JSON report schema for scores and factors terms
Report schema
A report schema refers to the documented shape and types of the JSON result.
Overall score
An overall score refers to the weighted readiness value from zero to one hundred.
Pipeline stage
A pipeline stage means that related factors are grouped by their role in retrieval and citation readiness.
Factor record
A factor record is defined as one score, maximum, status, value, evidence tier, and citation list.
Diagnostic
A diagnostic refers to a visible zero-over-zero observation excluded from the score.
Recommendation
A recommendation is a type of response that connects a measured gap to a possible page change.
Top-level result
{
"schemaVersion": 2,
"url": "https://example.com",
"overallScore": 68,
"grade": "D+",
"stages": { "technicalEligibility": {}, "retrievalAlignment": {} },
"categories": {},
"recommendations": [],
"rawData": {}
}Pipeline stages
| Field or option | Description |
|---|---|
technicalEligibility | Pass/fail gate with blockers and a percentage. |
retrievalAlignment | Structural, topical, and query-alignment measurements. |
citationFitness | Directness, grounding, relevance, freshness, and conditional gates. |
provenance | Authorship and organization-identity hygiene. |
Factor records
Each factor includes a name, score, maximum score, observed value, status, evidence tier, and paper citation identifiers. Diagnostics show 0/0 points and stay outside score denominators.
Recommendations
Each recommendation includes its category, factor, current value, priority, auditPoints, evidence, and citations. It may also include a direction, steps, code example, or link. auditPoints are internal weights, not additive citation gains.
How to use this reference
- Check schemaVersion before reading the result.
- Read technical eligibility before downstream stage percentages.
- Use category and factor records to explain the overall score.
- Keep evidence tiers and citations attached to displayed findings.
- Store the raw result when later comparisons must remain auditable.
Key takeaways
- The schema version is the first compatibility check.
- The overall score is a summary of weighted stage results.
- The factor is the smallest scored and evidenced record.
- The diagnostic is visible but excluded from the denominator.
- The recommendation is guidance, not a predicted citation gain.
Bottom line: Preserve the full JSON result whenever another system needs to explain or compare a score.
Official sources and verification
According to the npm package page, aiseo-audit publishes its current version and installation command [1]. According to the GitHub repository, the source code and project documentation are public [2].
According to the evidence map, every scored factor records an evidence tier and pipeline stage [3]. According to the release history, major versions document scoring changes that require new baselines [4]. According to the project license, aiseo-audit uses the MIT license[5].
- aiseo-audit on npm: package, version, and installation details.
- agencyenterprise/aiseo-audit: source code and documentation.
- aiseo-audit evidence map: factor tiers, stages, and research sources.
- aiseo-audit releases: version history and migration notes.
- MIT license: project license text.