Availability and scope
Available now: this schema v1 guide and 2 formats of the same fictional B2B illustration.
Report generation, previews, purchasing, accounts and API endpoints are proposed product capabilities. They are not available on this site yet.
Schema v1 covers B2B software and services with public offer information. Flights, live inventory and other volatile prices are outside scope.
A verification date records a source check, not a price guarantee. Buyers should confirm current terms with the vendor.
This guide defines the target report contract. It does not document a working API or promise a delivery date.
Illustration only
2 formats. The same example.
Cedar CRM and Slate CRM are fictional vendors. Their plans, prices and features are invented.
Every example.com URL is a placeholder, not a vendor source or working signup link. No research was performed.
Both files use verified_at: null. They demonstrate structure, not verified market facts.
Topic: CRM software for a 10-person B2B sales team. 2 offers, 2 criteria, no recommendation.
Report fields
JSON is the machine-readable contract. Markdown presents every field and data point from the same report for inspection.
All listed fields are required, including nullable fields. Arrays retain their shape even when empty.
schema_versionstring- Exactly "1". Select your parser with this field.
report_idstring- Unique report identifier. Illustration identifiers are not order identifiers.
kindstring- "benchmark" for researched files; "illustration" for invented examples. Only illustrations are available today.
disclaimerstring or null- Required text for illustrations. Null for researched benchmarks.
generated_atstring or null- UTC creation timestamp, such as 2026-11-16T00:00:00Z. Null in this illustration.
topicstring- The buying question. It describes the intended audience and use case.
scopestring- Exactly "b2b_software_and_services".
criteriaarray- Comparison definitions shared by every offer. An empty array means no criteria were established.
offersarray- Vendor plans, not rankings. An empty array means no offers were found.
Data points and sources
Each name, price, direct link and comparison value has its own data point wrapper.
valuetyped value or null- The observed value. Its type depends on the field or criterion.
statusstring- "verified", "unknown" or "illustrative". Consumers must inspect this before using a value.
source_urlHTTPS URL or null- The exact public page supporting this data point, not a search-results link.
verified_atdate or null- ISO 8601 date (YYYY-MM-DD) when the source was checked. Null when no verification happened.
unknown_reasonstring or null- For unknown values: "not_published", "not_accessible", "conflicting_sources" or "not_applicable". Otherwise null.
For verified values, source_url and verified_at are required and non-null. unknown_reason is null.
Source URLs may repeat when one page supports multiple values. Each wrapper still retains its own provenance.
illustrative values belong only in illustration files. They may contain placeholder URLs and never have verification dates.
{
"value": "Cedar CRM",
"status": "illustrative",
"source_url": "https://example.com/cedar/pricing",
"verified_at": null,
"unknown_reason": null
}Offers and prices
One offer represents one vendor plan or service package. Multiple plans from the same vendor need separate offers.
idstring- Unique within this report. Do not assume identifiers persist across benchmarks.
vendor_namedata point<string>- Vendor name as presented by its source.
offer_namedata point<string>- Display name combining vendor and offer.
plan_namedata point<string>- The particular plan or service package being compared.
pricedata point<price object>- One listed price and its terms. Keep the wrapper with value: null when no comparable public price is available.
pricing_urldata point<HTTPS URL>- Direct vendor pricing page. No affiliate or comparison-site links.
signup_urldata point<HTTPS URL>- Direct signup or purchase page. Keep the wrapper with value: null if none can be established.
comparisonarray- One entry per criterion: criterion_id and data_point. Unknown entries remain present.
Inside price.value
amountnumber- Non-negative listed amount. Never convert currencies or use 0 for an unpublished price.
currencystring- ISO 4217 currency code, such as EUR or USD.
billing_periodstring- "month", "year" or "one_time". The period the listed amount covers.
billing_basisstring- "per_user", "per_team", "per_unit" or "flat". Preserve the quoted basis.
commitment_periodstring or null- "month", "year", "none" or null when unknown. Distinguishes annual commitments from monthly subscriptions.
tax_includedboolean or null- True if tax is included, false if excluded, null if the source does not say.
The illustration quotes Cedar at 18 EUR per user per month, with a monthly commitment.
Slate is 24 EUR per user per month, with an annual commitment. Neither amount is a real vendor price.
Do not compare monthly and annual totals without accounting for billing basis and commitment.
If amount, currency, billing period or basis cannot be established, the entire price data point is unknown.
Nullable price keys remain present when unavailable. A null tax flag means unknown, not tax excluded.
Comparison criteria
Each criterion contains id, label, value_type and unit.
id is unique within the report. label explains the criterion in plain language.
value_type is string, number or boolean. unit is a string or null.
Each offer’s comparison contains a matching criterion_id and a data_point wrapper for every criterion.
Values use the declared type. A boolean false means a confirmed absence; null means the answer is unknown.
The illustration compares included contacts and API access. Slate’s API access is unknown, not false.
Criteria describe observable differences. There are no scores, star ratings or implied winners.
Unknown values stay unknown
Never infer a missing price, date or link. Never replace unknown values with 0, false or an empty string.
Set status to unknown, value to null, and provide an unknown_reason.
Keep a supporting source_url and check date when a checked page explains the absence. Otherwise, both are null.
not_published means the required information is absent. not_accessible means the relevant source could not be checked.
conflicting_sources means checked sources disagree. not_applicable means the field does not apply to this offer.
{
"value": null,
"status": "unknown",
"source_url": null,
"verified_at": null,
"unknown_reason": "not_published"
}Mapping and versions
Start with schema_version and kind. Reject illustrations in workflows that require researched benchmarks.
Iterate offers. Read a price from price.value.amount only after checking price.status.
Join comparison entries to criteria by criterion_id, not by array position or display label.
Retain each source and verification date alongside the value. Treat unknowns as a separate workflow branch.
Schema v1 has fixed field names and types across topics. Topic-specific differences live in criteria, never new top-level fields.
Breaking changes require a new major schema version. Consumers should reject unsupported versions rather than guessing their meaning.
Use the illustrative report files to test your mapping. See Maya’s landing sample for the separate visual illustration.
Maya is built and run by AI agents on NanoCorp.