schemaorg-kit 1.1.1 → 1.3.0

package/dist/index.mjs

@@ -56,6 +56,8 @@ import { z as z3 } from "zod";
 import { z as z2 } from "zod";
 var PersonOrOrgRef = z2.union([
   z2.string(),
+  // @id-only reference for @graph cross-referencing (e.g. { "@id": "https://example.com/#organization" })
+  z2.object({ "@id": z2.string() }),
   // Accept any Person or Organization object — including full schema outputs via .toObject().
   // .catchall() allows extra fields; name/url are optional to match ThingSchema's base types.
   z2.object({ "@type": z2.literal("Person") }).catchall(z2.unknown()),
@@ -65,6 +67,7 @@ var PersonOrOrgRef = z2.union([
 // src/types/shared/ImageObject.ts
 var ImageObjectSchema = z3.object({
   "@type": z3.literal("ImageObject").default("ImageObject"),
+  "@id": z3.string().optional(),
   url: z3.url(),
   contentUrl: z3.url().optional(),
   width: z3.union([
@@ -121,8 +124,9 @@ var ThingSchema = z4.object({
   sameAs: z4.union([z4.url(), z4.array(z4.url())]).optional(),
   alternateName: z4.string().optional(),
   // Relationships (loose refs to avoid circular type inference)
-  subjectOf: AnyThingRef.optional(),
-  mainEntityOfPage: z4.union([z4.url(), AnyThingRef]).optional()
+  // All accept { "@id": "..." } for @graph cross-referencing
+  subjectOf: z4.union([z4.object({ "@id": z4.string() }), AnyThingRef]).optional(),
+  mainEntityOfPage: z4.union([z4.url(), z4.object({ "@id": z4.string() }), AnyThingRef]).optional()
 });
 function extendThing(type, shape) {
   return ThingSchema.extend({
@@ -180,6 +184,7 @@ import { z as z15 } from "zod";
 import { z as z8 } from "zod";
 var ContactPointSchema = z8.object({
   "@type": z8.literal("ContactPoint").default("ContactPoint"),
+  "@id": z8.string().optional(),
   telephone: z8.string().optional(),
   contactType: z8.string().optional(),
   // e.g. "customer support", "sales"
@@ -381,7 +386,10 @@ var OfferSchema = z12.object({
   validThrough: z12.string().optional(),
   // ISO 8601
   url: z12.url().optional(),
-  seller: z12.object({ "@type": z12.string(), name: z12.string() }).optional(),
+  seller: z12.union([
+    z12.object({ "@id": z12.string() }),
+    z12.object({ "@type": z12.string(), name: z12.string() })
+  ]).optional(),
   category: z12.string().optional(),
   inventoryLevel: z12.object({
     "@type": z12.literal("QuantitativeValue").default("QuantitativeValue"),
@@ -394,7 +402,10 @@ var OfferSchema = z12.object({
     z12.array(UnitPriceSpecificationSchema)
   ]).optional(),
   shippingDetails: z12.union([OfferShippingDetailsSchema, z12.array(OfferShippingDetailsSchema)]).optional(),
-  hasMerchantReturnPolicy: z12.lazy(() => z12.object({ "@type": z12.string() }).catchall(z12.unknown())).optional()
+  hasMerchantReturnPolicy: z12.union([
+    z12.object({ "@id": z12.string() }),
+    z12.lazy(() => z12.object({ "@type": z12.string() }).catchall(z12.unknown()))
+  ]).optional()
 });
 var MerchantReturnPolicySchema = z12.object({
   "@type": z12.literal("MerchantReturnPolicy").default("MerchantReturnPolicy"),
@@ -573,8 +584,9 @@ var OrganizationSchema = extendThing("Organization", {
   interactionStatistic: z15.union([InteractionCounterSchema, z15.array(InteractionCounterSchema)]).optional(),
   agentInteractionStatistic: z15.union([InteractionCounterSchema, z15.array(InteractionCounterSchema)]).optional(),
   // Hierarchical organization (loose refs to avoid circular type inference):
-  subOrganization: NestedOrgRef.optional(),
-  parentOrganization: NestedOrgRef.optional(),
+  // Accept { "@id": "..." } for @graph cross-referencing
+  subOrganization: z15.union([z15.object({ "@id": z15.string() }), NestedOrgRef]).optional(),
+  parentOrganization: z15.union([z15.object({ "@id": z15.string() }), NestedOrgRef]).optional(),
   sameAs: z15.union([z15.url(), z15.array(z15.url())]).optional()
 });
 var createOrganization = makeFactory(OrganizationSchema);
@@ -627,7 +639,10 @@ var ReviewSchema = z16.object({
   // ISO 8601 date
   publisher: PersonOrOrgRef.optional(),
   // itemReviewed: any Thing — kept loose to avoid circular imports
-  itemReviewed: z16.lazy(() => z16.object({ "@type": z16.string() }).passthrough()).optional(),
+  itemReviewed: z16.union([
+    z16.object({ "@id": z16.string() }),
+    z16.lazy(() => z16.object({ "@type": z16.string() }).catchall(z16.unknown()))
+  ]).optional(),
   name: z16.string().optional(),
   // Review headline
   url: z16.url().optional(),
@@ -636,9 +651,12 @@ var ReviewSchema = z16.object({
 });
 var EmployerAggregateRatingSchema = AggregateRatingSchema.extend({
   "@type": z16.literal("EmployerAggregateRating").default("EmployerAggregateRating"),
-  itemReviewed: z16.lazy(
-    () => z16.object({ "@type": z16.string(), name: z16.string() }).passthrough()
-  ).optional()
+  itemReviewed: z16.union([
+    z16.object({ "@id": z16.string() }),
+    z16.lazy(
+      () => z16.object({ "@type": z16.string(), name: z16.string() }).catchall(z16.unknown())
+    )
+  ]).optional()
 });
 
 // src/types/things/Product.ts
@@ -852,6 +870,7 @@ var EventAttendanceMode = z19.enum([
 ]).transform((v) => `https://schema.org/${v}`);
 var PlaceRef = z19.union([
   z19.string(),
+  z19.object({ "@id": z19.string() }),
   z19.object({
     "@type": z19.literal("Place").default("Place"),
     name: z19.string().optional(),
@@ -884,11 +903,17 @@ var EventSchema = extendThing("Event", {
   previousStartDate: z19.string().optional(),
   // ISO 8601 — for rescheduled events
   aggregateRating: AggregateRatingSchema.optional(),
-  // Sub-events:
+  // Sub-events (accept @id refs for @graph cross-referencing):
   subEvent: z19.lazy(
-    () => z19.array(z19.object({ "@type": z19.string() }).catchall(z19.unknown()))
+    () => z19.array(z19.union([
+      z19.object({ "@id": z19.string() }),
+      z19.object({ "@type": z19.string() }).catchall(z19.unknown())
+    ]))
   ).optional(),
-  superEvent: z19.lazy(() => z19.object({ "@type": z19.string() }).catchall(z19.unknown())).optional(),
+  superEvent: z19.union([
+    z19.object({ "@id": z19.string() }),
+    z19.lazy(() => z19.object({ "@type": z19.string() }).catchall(z19.unknown()))
+  ]).optional(),
   // Additional:
   inLanguage: z19.union([
     z19.string(),
@@ -943,9 +968,12 @@ var PlaceSchema = extendThing("Place", {
       value: z21.union([z21.boolean(), z21.string(), z21.number()])
     })
   ).optional(),
-  containedInPlace: z21.lazy(
-    () => z21.object({ "@type": z21.string(), name: z21.string().optional() }).catchall(z21.unknown())
-  ).optional()
+  containedInPlace: z21.union([
+    z21.object({ "@id": z21.string() }),
+    z21.lazy(
+      () => z21.object({ "@type": z21.string(), name: z21.string().optional() }).catchall(z21.unknown())
+    )
+  ]).optional()
 });
 var createPlace = makeFactory(PlaceSchema);
 
@@ -996,11 +1024,15 @@ var LocalBusinessSchema = PlaceSchema.extend({
   iso6523Code: z22.string().optional(),
   hasMerchantReturnPolicy: MerchantReturnPolicySchema.optional(),
   sameAs: z22.union([z22.url(), z22.array(z22.url())]).optional(),
-  // Departments (nested LocalBusiness):
+  // Departments (nested LocalBusiness — accept @id refs for @graph cross-referencing):
   department: z22.lazy(
     () => z22.union([
+      z22.object({ "@id": z22.string() }),
       z22.object({ "@type": z22.string() }).catchall(z22.unknown()),
-      z22.array(z22.object({ "@type": z22.string() }).catchall(z22.unknown()))
+      z22.array(z22.union([
+        z22.object({ "@id": z22.string() }),
+        z22.object({ "@type": z22.string() }).catchall(z22.unknown())
+      ]))
     ])
   ).optional(),
   // Opening hours in string format (alternative to openingHoursSpecification):
@@ -1140,12 +1172,15 @@ var BookSchema = z24.object({
   sameAs: z24.union([z24.string(), z24.array(z24.string())]).optional(),
   /** Specific editions — each may have ReadAction / BorrowAction */
   workExample: z24.union([BookEditionSchema, z24.array(BookEditionSchema)]).optional(),
-  /** Publisher of the primary edition */
-  publisher: z24.object({
-    "@type": z24.union([z24.literal("Organization"), z24.literal("Person")]),
-    name: z24.string(),
-    url: z24.url().optional()
-  }).optional(),
+  /** Publisher of the primary edition (accept @id refs for @graph cross-referencing) */
+  publisher: z24.union([
+    z24.object({ "@id": z24.string() }),
+    z24.object({
+      "@type": z24.union([z24.literal("Organization"), z24.literal("Person")]),
+      name: z24.string(),
+      url: z24.url().optional()
+    })
+  ]).optional(),
   /** Number of pages */
   numberOfPages: z24.number().int().positive().optional(),
   /** Original publication year */
@@ -1155,7 +1190,10 @@ var BookSchema = z24.object({
   /** BCP 47 language tag */
   inLanguage: z24.string().optional(),
   /** Aggregate rating across editions */
-  aggregateRating: z24.lazy(() => z24.object({ "@type": z24.string() }).catchall(z24.unknown())).optional()
+  aggregateRating: z24.union([
+    z24.object({ "@id": z24.string() }),
+    z24.lazy(() => z24.object({ "@type": z24.string() }).catchall(z24.unknown()))
+  ]).optional()
 });
 var createBook = makeFactory(BookSchema);
 
@@ -1194,11 +1232,14 @@ var CreativeWorkSchema = extendThing("CreativeWork", {
       cssSelector: z25.string().optional()
     })
   ).optional(),
-  // For subscription / paywalled content
-  isPartOf: z25.object({
-    "@type": z25.string(),
-    name: z25.string().optional()
-  }).optional(),
+  // For subscription / paywalled content (accept @id refs for @graph cross-referencing)
+  isPartOf: z25.union([
+    z25.object({ "@id": z25.string() }),
+    z25.object({
+      "@type": z25.string(),
+      name: z25.string().optional()
+    })
+  ]).optional(),
   text: z25.string().optional(),
   abstract: z25.string().optional(),
   encodingFormat: z25.string().optional(),
@@ -1234,9 +1275,10 @@ var NewsArticleSchema = ArticleSchema.extend({
 });
 var BlogPostingSchema = ArticleSchema.extend({
   "@type": z26.literal("BlogPosting").default("BlogPosting"),
-  sharedContent: z26.lazy(
-    () => z26.object({ "@type": z26.string() }).passthrough()
-  ).optional()
+  sharedContent: z26.union([
+    z26.object({ "@id": z26.string() }),
+    z26.lazy(() => z26.object({ "@type": z26.string() }).catchall(z26.unknown()))
+  ]).optional()
 });
 var createArticle = makeFactory(ArticleSchema);
 var createNewsArticle = makeFactory(NewsArticleSchema);
@@ -1246,9 +1288,12 @@ var createBlogPosting = makeFactory(BlogPostingSchema);
 import { z as z27 } from "zod";
 var WebPageSchema = CreativeWorkSchema.extend({
   "@type": z27.literal("WebPage").default("WebPage"),
-  breadcrumb: z27.lazy(
-    () => z27.object({ "@type": z27.literal("BreadcrumbList") }).catchall(z27.unknown())
-  ).optional(),
+  breadcrumb: z27.union([
+    z27.object({ "@id": z27.string() }),
+    z27.lazy(
+      () => z27.object({ "@type": z27.literal("BreadcrumbList") }).catchall(z27.unknown())
+    )
+  ]).optional(),
   lastReviewed: z27.string().optional(),
   reviewedBy: PersonOrOrgRef.optional(),
   speakable: z27.object({
@@ -1257,8 +1302,14 @@ var WebPageSchema = CreativeWorkSchema.extend({
     xpath: z27.union([z27.string(), z27.array(z27.string())]).optional()
   }).optional(),
   significantLink: z27.union([z27.url(), z27.array(z27.url())]).optional(),
-  mainContentOfPage: z27.object({ "@type": z27.string() }).catchall(z27.unknown()).optional(),
-  primaryImageOfPage: z27.object({ "@type": z27.string() }).catchall(z27.unknown()).optional(),
+  mainContentOfPage: z27.union([
+    z27.object({ "@id": z27.string() }),
+    z27.object({ "@type": z27.string() }).catchall(z27.unknown())
+  ]).optional(),
+  primaryImageOfPage: z27.union([
+    z27.object({ "@id": z27.string() }),
+    z27.object({ "@type": z27.string() }).catchall(z27.unknown())
+  ]).optional(),
   relatedLink: z27.union([z27.url(), z27.array(z27.url())]).optional()
 });
 var createWebPage = makeFactory(WebPageSchema);
@@ -1293,8 +1344,11 @@ var WebSiteSchema = CreativeWorkSchema.extend({
   publisher: PersonOrOrgRef.optional(),
   // Site-level metadata
   copyrightYear: z28.number().int().optional(),
-  // isPartOf — rarely used for WebSite itself but allowed
-  isPartOf: z28.lazy(() => z28.object({ "@type": z28.string() }).catchall(z28.unknown())).optional()
+  // isPartOf — rarely used for WebSite itself but allowed (accept @id refs for @graph)
+  isPartOf: z28.union([
+    z28.object({ "@id": z28.string() }),
+    z28.lazy(() => z28.object({ "@type": z28.string() }).catchall(z28.unknown()))
+  ]).optional()
 });
 var createWebSite = makeFactory(WebSiteSchema);
 
@@ -1702,7 +1756,7 @@ var JobPostingSchema = z37.object({
   // Required by Google:
   title: z37.string(),
   description: z37.string(),
-  hiringOrganization: HiringOrgRef,
+  hiringOrganization: z37.union([z37.object({ "@id": z37.string() }), HiringOrgRef]),
   jobLocation: z37.union([JobLocationRef, z37.array(JobLocationRef)]).optional(),
   datePosted: z37.string(),
   // ISO 8601 date
@@ -1816,7 +1870,10 @@ var QuizSchema = CreativeWorkSchema.extend({
   "@type": z38.literal("Quiz").default("Quiz"),
   name: z38.string().optional(),
   educationalLevel: z38.string().optional(),
-  about: z38.lazy(() => z38.object({ "@type": z38.string() }).catchall(z38.unknown())).optional(),
+  about: z38.union([
+    z38.object({ "@id": z38.string() }),
+    z38.lazy(() => z38.object({ "@type": z38.string() }).catchall(z38.unknown()))
+  ]).optional(),
   hasPart: z38.array(QuestionSchema).optional(),
   educationalAlignment: z38.union([AlignmentObjectSchema, z38.array(AlignmentObjectSchema)]).optional()
 });
@@ -1856,9 +1913,12 @@ var DiscussionForumPostingSchema = CreativeWorkSchema.extend({
   image: ImageOrUrl.optional(),
   /** "published", "draft", "deleted" — or a schema.org enum URL */
   creativeWorkStatus: z39.string().optional(),
-  mainEntityOfPage: z39.union([z39.url(), z39.object({}).catchall(z39.unknown())]).optional(),
-  // For reposts:
-  sharedContent: z39.lazy(() => z39.object({ "@type": z39.string() }).catchall(z39.unknown())).optional(),
+  mainEntityOfPage: z39.union([z39.url(), z39.object({ "@id": z39.string() }), z39.object({}).catchall(z39.unknown())]).optional(),
+  // For reposts (accept @id refs for @graph cross-referencing):
+  sharedContent: z39.union([
+    z39.object({ "@id": z39.string() }),
+    z39.lazy(() => z39.object({ "@type": z39.string() }).catchall(z39.unknown()))
+  ]).optional(),
   interactionStatistic: z39.union([InteractionCounterSchema, z39.array(InteractionCounterSchema)]).optional()
 });
 var createDiscussionForumPosting = makeFactory(
@@ -1895,13 +1955,17 @@ var createItemList = makeFactory(ItemListSchema);
 import { z as z41 } from "zod";
 var ProfilePageSchema = WebPageSchema.extend({
   "@type": z41.literal("ProfilePage").default("ProfilePage"),
-  // mainEntity: the person or org this profile is about (loose ref to avoid circular imports)
-  mainEntity: z41.lazy(
-    () => z41.object({ "@type": z41.string() }).catchall(z41.unknown())
-  ).optional(),
+  // mainEntity: the person or org this profile is about (accept @id refs for @graph)
+  mainEntity: z41.union([
+    z41.object({ "@id": z41.string() }),
+    z41.lazy(() => z41.object({ "@type": z41.string() }).catchall(z41.unknown()))
+  ]).optional(),
   // hasPart: content published by/about this profile subject
   hasPart: z41.array(
-    z41.lazy(() => z41.object({ "@type": z41.string() }).catchall(z41.unknown()))
+    z41.union([
+      z41.object({ "@id": z41.string() }),
+      z41.lazy(() => z41.object({ "@type": z41.string() }).catchall(z41.unknown()))
+    ])
   ).optional(),
   dateCreated: z41.string().optional(),
   dateModified: z41.string().optional()
@@ -2116,6 +2180,104 @@ function createGraph(nodes) {
   return graph;
 }
 
+// src/core/ids.ts
+var SchemaIds = class {
+  constructor(origin) {
+    this.origin = origin;
+  }
+  /** @internal Build an ID from origin + fragment */
+  id(fragment) {
+    return `${this.origin}/#${fragment}`;
+  }
+  // ── Well-known entity IDs ───────────────────────────────────────────────
+  // Things
+  organization() {
+    return this.id("organization");
+  }
+  localBusiness() {
+    return this.id("localbusiness");
+  }
+  person() {
+    return this.id("person");
+  }
+  product() {
+    return this.id("product");
+  }
+  event() {
+    return this.id("event");
+  }
+  place() {
+    return this.id("place");
+  }
+  movie() {
+    return this.id("movie");
+  }
+  // Creative works
+  website() {
+    return this.id("website");
+  }
+  webpage() {
+    return this.id("webpage");
+  }
+  article() {
+    return this.id("article");
+  }
+  breadcrumb() {
+    return this.id("breadcrumb");
+  }
+  dataset() {
+    return this.id("dataset");
+  }
+  recipe() {
+    return this.id("recipe");
+  }
+  course() {
+    return this.id("course");
+  }
+  softwareApplication() {
+    return this.id("softwareapplication");
+  }
+  // Intangibles & other
+  faqPage() {
+    return this.id("faqpage");
+  }
+  jobPosting() {
+    return this.id("jobposting");
+  }
+  vacationRental() {
+    return this.id("vacationrental");
+  }
+  profilePage() {
+    return this.id("profilepage");
+  }
+  // ── Custom IDs ──────────────────────────────────────────────────────────
+  /**
+   * Generate an ID with any custom fragment.
+   * @example ids.custom("hero-banner") // "https://example.com/#hero-banner"
+   */
+  custom(fragment) {
+    return this.id(fragment);
+  }
+  /**
+   * Generate an ID scoped to a specific page path.
+   * @example ids.forPath("/about", "webpage") // "https://example.com/about#webpage"
+   */
+  forPath(path, fragment) {
+    return `${this.origin}${path}#${fragment}`;
+  }
+  // ── Reference helper ────────────────────────────────────────────────────
+  /**
+   * Returns a `{ "@id": "..." }` reference object for cross-referencing
+   * entities within a @graph. Pass to fields like publisher, organizer, etc.
+   *
+   * @example
+   * createWebSite({ publisher: ids.ref("organization"), ... })
+   */
+  ref(fragment) {
+    return { "@id": this.id(fragment) };
+  }
+};
+
 // src/helpers/breadcrumb.ts
 import { z as z43 } from "zod";
 var BreadcrumbListSchema = z43.object({
@@ -2279,6 +2441,7 @@ export {
   RecipeSchema,
   ReviewSchema,
   SchemaGraph,
+  SchemaIds,
   SchemaNode,
   SeekToActionSchema,
   ServicePeriodSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schemaorg-kit",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Type-safe schema.org structured data builder — all Google rich result types, Zod validation, JSON-LD @graph",
   "keywords": [
     "schema.org",