Menu

Example validation

Verification Required

Example CI validation.

A docs gate for example manifests, status labels, rendered routes, evidence links, validation modes, reviewers, and limits.

Validation Command

Shell

Example manifest validation command

Run from the Gatsby app directory to validate every example manifest.

cd docs.stornamics.com
npm run validate:examples

The command runs scripts/validate-example-manifests.mjs.

Text

Expected Output

Expected summary when all current example bundles satisfy the manifest gate.

Example manifest validation passed for 5 manifests (tested: 3, manually-verified: 0, illustrative: 2, future: 0).

Validation Snapshot

Manifests
5
Tested
3
Illustrative
2
Next
DOCS-077

Gate Flow

  1. Find ManifestsScan every docs/examples/{product}/{example-slug}/manifest.yaml file.
  2. Check StatusAllow only tested, manually-verified, illustrative, or future.
  3. Check RoutesConfirm docs_pages routes resolve to Gatsby pages and match the product scope.
  4. Check EvidenceVerify internal docs evidence paths exist and the manifest has limits and reviewers.
  5. Apply RulesEnforce status-specific validation.command and validation.mode combinations.

Validation Guardrails

Shape, Not Runtime

The gate validates manifest metadata and rendered links. Product runtime behavior still belongs to product tests and reviewer notes.

Status Drives Rules

Tested examples need executable validation commands; illustrative and future examples must stay n/a and non-runnable.

Evidence Stays Nearby

Every manifest needs reviewers, evidence, docs pages, validation mode, and limits before it can be linked.

Gate Rules

Example manifest checks
CheckRequirement
Manifest locationManifest files must live at docs/examples/{product}/{example-slug}/manifest.yaml.
ProductProduct must be objectdb, message-broker, logdb, concordia, or cross-product, and it must match the folder.
Required fieldsid, product, status, language, owner, reviewers, docs_pages, evidence, limits, validation.command, and validation.mode are required.
Rendered routesdocs_pages routes must start and end with / and resolve to an existing Gatsby page.
Evidence pathsDocs evidence paths must exist; product-evidence placeholders are allowed.
TODO guardRequired fields, lists, validation command, and validation mode must not contain TODO.

Status Rules

Status-specific validation requirements
StatusValidationLink Policy
testedRequires a non-none validation mode and a validation command that is not n/a.Can be linked from guides and product next steps when evidence and limits stay nearby.
manually-verifiedRequires validation.mode manual plus reviewer-run evidence in the source bundle or guide.Can be linked from guides when reviewer rationale is visible.
illustrativeRequires validation.mode none and a validation.command beginning with n/a.Keep out of quickstart proof and label as architecture or call-shape only.
futureRequires validation.mode none and a validation.command beginning with n/a.Keep out of current quickstarts and references unless the future label is visible.

Manifest Coverage

Current example bundles covered by the gate
BundleStatusRendered Page
docs/examples/objectdb/s3-sdk-examples/illustrative/products/objectdb/guides/s3-sdk-examples/
docs/examples/message-broker/rust-sdk-examples/tested/products/message-broker/guides/rust-sdk-examples/
docs/examples/logdb/otel-collector-examples/tested/products/logdb/guides/otel-collector-examples/
docs/examples/concordia/local-curl-examples/tested/products/concordia/guides/local-curl-examples/
docs/examples/cross-product/community-support-snapshot/illustrative/guides/community-support-snapshot/

Evidence

DOCS-063 evidence map
AreaEvidenceStatus
Example manifest gatescripts/validate-example-manifests.mjspending
Package scriptdocs.stornamics.com/package.jsonpending
Example source layoutdocs/examples/README.mdpending
Example strategy and CI policyDOCS-057 and /guides/examples/pending
Existing example manifestsDOCS-058 through DOCS-062pending

Limits

This gate validates example manifest metadata and rendered docs links. It does not execute product examples, install SDKs, start external services, or approve product runtime, support, security, privacy, availability, performance, scale, compliance, release readiness, or GA claims.

Safe Next Steps

  • Available: DOCS-057

    Use example strategy

    Review the source layout, status policy, page mapping, and review gates for examples.

  • Available: DOCS-062

    Review community support snapshot

    See how illustrative cross-product examples stay separate from tested product behavior.

  • Available: DOCS-064

    Use search and filtering

    Find validated examples and their owning docs pages by product, content type, maturity, audience, and keyword.

  • Available: DOCS-065

    Use version and status filtering

    Compare docs surfaces by version or profile scope, maturity state, product, and evidence.

  • Available: DOCS-066

    Use code tabs and copy controls

    Use reusable tabs, copy buttons, and expected-output blocks on rendered examples.

  • Available: DOCS-092

    Plan public feedback intake

    Use the public feedback route for approved issue-template, support, redaction, page-health, privacy, and triage boundaries.

  • Available: DOCS-068

    Use page health analytics

    Track broken journeys, failed searches, page-feedback event shape review, stale pages, and no-result searches in the browser-local health dashboard.

  • Available: DOCS-069

    Use accessibility and performance hardening

    Use the shared skip link, named landmarks, visible focus treatment, navigation state, and local load budgets across docs UX surfaces.

  • Available: DOCS-070

    Use mobile navigation polish

    Use compact product-section rails and generated in-page anchors on long product routes.

  • Available: DOCS-071

    Use frontmatter schema validation

    Run the required metadata gate for product, audience, content type, maturity, owner, and last-reviewed fields.

  • Available: DOCS-072

    Use link checking

    Run docs route, file, navigation, and anchor checks with retried external warning reports.

  • Available: DOCS-073

    Use snippet validation

    Run manifest-backed checks for opted-in code snippets, command examples, and expected output blocks.

  • Available: DOCS-074

    Use claim and status linting

    Run maturity-sensitive checks for unsafe, overbroad, or review-bound claims and waiver metadata.

  • Available: DOCS-075

    Use PR templates and CODEOWNERS

    Use Azure PR templates, CODEOWNERS routing, and validation for review evidence and screenshots.

  • Available: DOCS-076

    Use release docs checklist

    Use release checklist coverage for changelog entries, limitations, references, migration notes, and validation evidence.

  • Next: DOCS-077

    Start contributor guide

    Write the community contribution guide for setup, content types, review flow, and expected conduct.