From 6d373e6938f84117d94fc879cb435f53d9c46485 Mon Sep 17 00:00:00 2001
From: Lin Hugo <hugo970217@gmail.com>
Date: Tue, 14 Jul 2026 16:57:59 -0700
Subject: [PATCH] docs: document reusing a property's type via leaf types

Add a README section showing that a property's type can be extracted from
a concrete `...Leaf` interface (e.g. `OrganizationLeaf['image']`), avoiding
the `Exclude<Organization, string>[...]` workaround needed when indexing the
union alias. Documents the request in #50.

Includes a compile-time test asserting the extracted property types work.
---
 README.md                                 | 16 ++++++++++++++++
 packages/schema-dts/test/leaf_property.ts | 15 +++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 packages/schema-dts/test/leaf_property.ts

diff --git a/README.md b/README.md
index e154845..d7758b1 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,22 @@ const p: WithContext<Person> = {
 };
 ```
 
+### Reusing a property's type
+
+Every Schema.org type is also exported as a concrete "leaf" interface (e.g.
+`OrganizationLeaf`) alongside its union alias (`Organization`). Indexing the
+union alias to grab a single property's type fails, because the alias also
+includes an id-reference `string` that has no properties. Index the leaf
+interface instead:
+
+```ts
+import type {OrganizationLeaf} from 'schema-dts';
+
+// Previously required Exclude<Organization, string>['image'].
+type OrgImage = OrganizationLeaf['image'];
+type OrgLogo = OrganizationLeaf['logo'];
+```
+
 ### Merging multiple concrete types
 
 Some Schema.org objects can legitimately carry multiple concrete `@type` values.
diff --git a/packages/schema-dts/test/leaf_property.ts b/packages/schema-dts/test/leaf_property.ts
new file mode 100644
index 0000000..815388b
--- /dev/null
+++ b/packages/schema-dts/test/leaf_property.ts
@@ -0,0 +1,15 @@
+import type {OrganizationLeaf} from '../dist/schema';
+
+// A property's type can be extracted from the concrete leaf interface. Indexing
+// the union alias `Organization` instead would fail, because that alias also
+// includes an id-reference `string` with no properties.
+type OrgImage = OrganizationLeaf['image'];
+type OrgName = OrganizationLeaf['name'];
+
+const _image: OrgImage = 'https://acme.com/logo.png';
+
+const _name: OrgName = 'Acme Corp';
+
+// The extracted type still rejects invalid values.
+// @ts-expect-error image is not a number.
+const _bad: OrgImage = 42;