WORK-628
ID:WORK-628Status:done

Spike: @adobe/structured-data-validator over the SEO baseline

SPEC-145 D25 bans schema in user composition definitions until a mechanical check exists, and names the candidate:

Priority:mediumComplexity:simpleMilestone:v0.40.0Source:SPEC-145
main View source

Criteria completion

Criteria completion: 3 of 3 (100%) checked; history from Oct 8 to Oct 80%25%50%75%100%Oct 8Oct 8

Relationships

Implements 1
Related 4
Branches 2
main current done
claude/v040-sd-validator-spike doneclaude/post-v0.38-roadmap-jb7pie done
History 5
  1. fa3deff
    • ☑ `@adobe/structured-data-validator` has been run over `contracts/seo-baseline/`, and its findings (noise, and which known defects it catches) are recorded as the evidence for or against lifting D25's ban (D25)
    • ☑ How the schema.org vocabulary is obtained, pinned and updated is recorded, since D25 rests on consuming it rather than shipping one
    • ☑ The recommendation is recorded in SPEC-145 under D25, with a follow-up work item filed if it is to become a `refrakt validate` check
    by bjornolofandersson
  2. 0a79781
    Content editedby Claude
    plan: mark WORK-628 done
  3. a1e7a18
    Content editedby Claude
    spike(seo): run @adobe/structured-data-validator over the SEO baseline (
  4. 481b6b4
    Created (ready)by bjornolofandersson
  5. b3823f6
    Content editedby Claude
    plan: draft v0.40.0 — The first composed rune

Acceptance Criteria

  • @adobe/structured-data-validator has been run over contracts/seo-baseline/, and its findings (noise, and which known defects it catches) are recorded as the evidence for or against lifting D25's ban (D25)
  • How the schema.org vocabulary is obtained, pinned and updated is recorded, since D25 rests on consuming it rather than shipping one
  • The recommendation is recorded in SPEC-145 under D25, with a follow-up work item filed if it is to become a refrakt validate check

Resolution

Completed: 2026-10-08

Branch: claude/v040-sd-validator-spike PR: refrakt-md/refrakt#676

What was done

  • scripts/sd-validator-spike.mjs runs @adobe/structured-data-validator 1.7.0 against schema.org 30.1, pinned by version and sha256. It covers today's baseline, the baseline at 306e18e, 83e86f6 and edc0608, and six synthetic probes. The validator is not a dependency of anything; it is a scratch install passed in SDV_DIR.
  • plan/specs/SPEC-145-composed-runes.md: the D25 "Spike result" section records noise, catch rate, probes, cost, how the vocabulary is obtained and pinned, and the recommendation.
  • Filed BUG-033: byArtist on MusicPlaylist, and duration on Chapter and on CreativeWork, found by the schema.org layer.
  • Filed WORK-629 (draft): the schema.org layer as a maintainer-side CI check over the baseline.

Notes

  • Recommendation: keep D25's ban on user schema. The schema.org layer checks only that a type exists and that each property is in the type's domain. It had zero false positives, but it caught 3 of 17 recorded defects, one of them incidentally. It misses wrong types, bare types, wrong values and wrong membership. The rich-result layer is eligibility noise on refrakt's output: 196 of 203 findings on today's baseline. So no refrakt validate follow-up was filed.
  • Spec premise that did not hold as written: the sandbox's egress policy refused schema.org, while GitHub raw (schemaorg/schemaorg data/releases/<v>/) worked. So "consume, don't ship" means network in validate, a vendored 229 KB-gzipped file, or a user-supplied one.
  • The library caches its vocabulary in a process-wide static, so the first vocabulary loaded wins. This matters for long-lived processes.