From 40a5ed2eb113edf0845ce8ef858eee2e4d1a2896 Mon Sep 17 00:00:00 2001
From: miguel gutierrez <miguel.gutierrezt@pucp.pe>
Date: Wed, 21 Jan 2026 14:53:09 +0000
Subject: [PATCH] docs: document ItemDataConfig and full-property examples

---
 .gitignore                                    |  2 ++
 .../src/model/fragments-model.ts              | 29 +++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/.gitignore b/.gitignore
index 9618ae7..526a65d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -134,3 +134,5 @@ resources/frags/test
 
 resources/asdf2.frag
 resources/asdf2.json
+
+.DS_Store
\ No newline at end of file
diff --git a/packages/fragments/src/FragmentsModels/src/model/fragments-model.ts b/packages/fragments/src/FragmentsModels/src/model/fragments-model.ts
index 8caf4cb..4ae14d2 100644
--- a/packages/fragments/src/FragmentsModels/src/model/fragments-model.ts
+++ b/packages/fragments/src/FragmentsModels/src/model/fragments-model.ts
@@ -445,8 +445,37 @@ export class FragmentsModel {
 
   /**
    * Get all the data of the specified items.
+   *
+   * By default, the API returns the item’s built-in attributes only.
+   * Relations are not traversed unless explicitly enabled via the `config`
+   * parameter.
+   *
    * @param ids - The IDs of the items to look up.
    * @param config - The configuration of the items data.
+   * Default configuration:
+   * ```ts
+   * {
+   *   attributesDefault: true,
+   *   relationsDefault: { attributes: false, relations: false },
+   * }
+   * ```
+   *
+   * @example
+   * // Retrieve all built-in attributes and all related entities (full graph)
+   * await getItemsData(ids, {
+   *   attributesDefault: true,
+   *   relationsDefault: { attributes: true, relations: true },
+   * });
+   *
+   * @example
+   * // Retrieve built-in attributes and Property Sets only (via IsDefinedBy)
+   * await getItemsData(ids, {
+   *   attributesDefault: true,
+   *   relations: {
+   *     IsDefinedBy: { attributes: true, relations: true },
+   *     DefinesOccurrence: { attributes: false, relations: false },
+   *   },
+   * });
    */
   async getItemsData(ids: Identifier[], config?: Partial<ItemsDataConfig>) {
     return this._itemsManager.getItemsData(this, ids, config);