doc(struct_to_gts_schema): update documentation regarding the struct_to_gts_schema macro usage

gts-macros/README.md

@@ -60,9 +60,13 @@ pub struct AuditEventV1 {
 
 // Runtime usage:
 fn example() {
-    // Access schema constants
-    let base_schema = BaseEventV1::<()>::GTS_JSON_SCHEMA_WITH_REFS;
-    let audit_schema = AuditEventV1::GTS_JSON_SCHEMA_WITH_REFS;
+    // Access schema IDs
+    let base_id = BaseEventV1::<()>::gts_schema_id();
+    let audit_id = AuditEventV1::gts_schema_id();
+
+    // Get schemas as JSON
+    let base_schema = BaseEventV1::<()>::gts_schema_with_refs_as_string_pretty();
+    let audit_schema = AuditEventV1::gts_schema_with_refs_as_string_pretty();
 
     // Generate instance IDs
     let event_id = AuditEventV1::gts_make_instance_id("evt-12345.v1");
@@ -815,9 +819,9 @@ gts generate-from-rust --source src/
 ```rust
 fn main() {
     // Access schemas at any level
-    println!("Base event schema: {}", BaseEventV1::<()>::GTS_JSON_SCHEMA_WITH_REFS);
-    println!("Audit event schema: {}", AuditEventV1::<()>::GTS_JSON_SCHEMA_WITH_REFS);
-    println!("Order placed schema: {}", OrderPlacedV1::GTS_JSON_SCHEMA_WITH_REFS);
+    println!("Base event schema: {}", BaseEventV1::<()>::gts_schema_with_refs_as_string_pretty());
+    println!("Audit event schema: {}", AuditEventV1::<()>::gts_schema_with_refs_as_string_pretty());
+    println!("Order placed schema: {}", OrderPlacedV1::gts_schema_with_refs_as_string_pretty());
 
     // Generate instance IDs
     let event_id = OrderPlacedV1::gts_make_instance_id("evt-12345.v1");
@@ -986,22 +990,25 @@ Example:
 }
 ```
 
-### Schema Constants
+### Schema Generation Methods
 
-The macro generates two schema variants with **zero runtime allocation**:
+The macro generates methods for runtime schema access:
 
-- **`GTS_JSON_SCHEMA_WITH_REFS`**: Uses `$ref` in `allOf` (most memory-efficient)
-- **`GTS_JSON_SCHEMA_INLINE`**: Currently identical; true inlining requires runtime resolution
+- **`gts_schema_with_refs()`**: Returns `serde_json::Value` with `$ref` in `allOf`
+- **`gts_schema_with_refs_as_string()`**: Returns compact JSON string
+- **`gts_schema_with_refs_as_string_pretty()`**: Returns pretty-printed JSON string
 
 ```rust
-// Both are compile-time constants - no allocation at runtime!
-let schema_with_refs = AuditEventV1::<()>::GTS_JSON_SCHEMA_WITH_REFS;
-let schema_inline = AuditEventV1::<()>::GTS_JSON_SCHEMA_INLINE;
-
-// Runtime schema resolution (when true inlining is needed)
-use gts::GtsStore;
-let store = GtsStore::new();
-let inlined_schema = store.resolve_schema(&schema_with_refs)?;
+// Get schema as JSON value
+let schema_value = AuditEventV1::<()>::gts_schema_with_refs();
+
+// Get schema as string (compact or pretty)
+let schema_compact = AuditEventV1::<()>::gts_schema_with_refs_as_string();
+let schema_pretty = AuditEventV1::<()>::gts_schema_with_refs_as_string_pretty();
+
+// Schema IDs use LazyLock for efficient one-time initialization
+let schema_id = AuditEventV1::gts_schema_id();
+let parent_id = AuditEventV1::gts_base_schema_id();
 ```
 
 ---

gts-macros/src/lib.rs

@@ -552,10 +552,13 @@ impl Parse for GtsSchemaArgs {
 ///
 /// ## 3. Runtime API
 ///
-/// The macro generates these associated items and implements the `GtsSchema` trait:
+/// The macro generates these associated methods and implements the `GtsSchema` trait:
 ///
-/// - `GTS_JSON_SCHEMA_WITH_REFS: &'static str` - JSON Schema with `allOf` + `$ref` for inheritance (most memory-efficient)
-/// - `GTS_JSON_SCHEMA_INLINE: &'static str` - JSON Schema with parent inlined (currently identical to `WITH_REFS`; true inlining requires runtime resolution)
+/// - `gts_schema_id() -> &'static GtsSchemaId` - Get the struct's GTS schema ID
+/// - `gts_base_schema_id() -> Option<&'static GtsSchemaId>` - Get parent schema ID (None for base structs)
+/// - `gts_schema_with_refs() -> serde_json::Value` - JSON Schema with `allOf` + `$ref` for inheritance
+/// - `gts_schema_with_refs_as_string() -> String` - Schema as compact JSON string
+/// - `gts_schema_with_refs_as_string_pretty() -> String` - Schema as pretty-printed JSON string
 /// - `gts_make_instance_id(segment: &str) -> gts::GtsInstanceId` - Generate an instance ID by appending
 ///   a segment to the schema ID. The segment must be a valid GTS segment (e.g., "a.b.c.v1")
 /// - `GtsSchema` trait implementation - Enables runtime schema composition for nested generic types
@@ -576,9 +579,9 @@ impl Parse for GtsSchemaArgs {
 ///
 /// # Memory Efficiency
 ///
-/// All generated constants are compile-time strings with **zero runtime allocation**:
-/// - `GTS_JSON_SCHEMA_WITH_REFS` uses `$ref` for optimal memory usage
-/// - `GTS_JSON_SCHEMA_INLINE` is identical at compile time (true inlining requires runtime schema resolution)
+/// Schema IDs use `LazyLock` for efficient one-time initialization with **zero allocation after first access**:
+/// - `gts_schema_id()` and `gts_base_schema_id()` return static references to `GtsSchemaId` instances
+/// - Schema generation methods create JSON on-demand using schemars and the `GtsSchema` trait
 ///
 /// # Example
 ///
@@ -599,8 +602,8 @@ impl Parse for GtsSchemaArgs {
 /// }
 ///
 /// // Runtime usage:
-/// let schema_with_refs = User::GTS_JSON_SCHEMA_WITH_REFS;
-/// let schema_inline = User::GTS_JSON_SCHEMA_INLINE;
+/// let schema_id = User::gts_schema_id();
+/// let schema_json = User::gts_schema_with_refs_as_string_pretty();
 /// let instance_id = User::gts_make_instance_id("vendor.marketplace.orders.order_created.v1");
 /// assert_eq!(instance_id.as_ref(), "gts.x.core.events.topic.v1~vendor.marketplace.orders.order_created.v1");
 /// ```