Skip to content

[BUG]: JSON-LD assemblyVersion / datePublished / operatingSystem are wrong #63

Description

@martyy-code

Bug Description

Three pieces of JSON-LD embedded in the docs site claim values that are not consistent with the actual state of the package and the docs content.

  1. APIReference schema hard-codes assemblyVersion: '1.0.0' in apps/web/src/app/docs/[[...slug]]/page.tsx. The published package is @deessejs/errors@1.4.0 (see packages/errors/package.json). Search engines and Schema.org-aware tooling that read APIReference.assemblyVersion will see a stale version that drifts further with every release.

  2. TechArticle schema stamps datePublished: new Date().toISOString() on every doc page. The same source says that doc (page X) was "published today" every time a crawler fetches it. There is also no MDX frontmatter field for "published" or "updated" today, so we have nowhere honest to read the value from; this is currently an unconditional lie.

  3. SoftwareApplication schema on the home page declares operatingSystem: 'Node.js 18+' (apps/web/src/app/(home)/page.tsx). The published engines.node is >=22.14.0 (packages/errors/package.json). The site advertises compatibility with versions the package explicitly does not support.

These three together make the structured data the site emits to crawlers confidently wrong.

Steps to Reproduce

  1. Run pnpm --filter web dev.
  2. Visit http://localhost:3000/docs/api-reference and view source → search for "@type":"APIReference" → observe assemblyVersion":"1.0.0".
  3. Visit http://localhost:3000/docs/error-factory (or any doc page) and view source → search for "@type":"TechArticle" → observe datePublished":"<today's ISO>". Repeat tomorrow; the value moves with the calendar, not with the content.
  4. Visit http://localhost:3000/ and view source → search for "@type":"SoftwareApplication" → observe operatingSystem\":\"Node.js 18+\".
  5. Compare against packages/errors/package.json:
    • \"version\": \"1.4.0\" ≠ JSON-LD 1.0.0.
    • \"engines\": { \"node\": \">=22.14.0\" } ≠ JSON-LD Node.js 18+.

Expected Behavior

  • APIReference.assemblyVersion should track the package's current version field at build time (e.g. import version from @deessejs/errors/package.json, or read packages/errors/package.json directly from apps/web/).
  • TechArticle.datePublished should reflect a real publication date. Preferred option: extend pageSchema in apps/web/source.config.ts with an optional publishedAt (z.iso.date()), surface publishedAt on the page data, and fall back to null (omit the field) when not set. Drop dateModified if no parallel field is added.
  • SoftwareApplication.operatingSystem should match engines.node, e.g. \">=22.14.0\" or \"Node.js >=22.14.0\". Prefer reading from packages/errors/package.json so it stays in sync.

Actual Behavior

JSON-LD output claims:

  • assemblyVersion\":\"1.0.0\" for a 1.4.0 package.
  • datePublished\":\"<today>\" on every doc page, every fetch.
  • operatingSystem\":\"Node.js 18+\" against a >=22.14.0 engines spec.

Environment

  • Node.js: 22.x
  • pnpm: 10.x
  • OS: Windows / macOS / Linux (reproducible on any)

Metadata

Metadata

Assignees

No one assigned

    Labels

    effort: sHalf a dayp1: highRequired for next releasestatus: readyValidated by Tech Lead, ready to pick uptype: bugBug / defect fix

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions