> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/fabric-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/fabric-knowledge-base/api/api-documentation/linkages.md). # Linkages ## 1. Minimal Payload Structure The minimal payload structure for a linkage is defined by the `BasicLinkage` schema: ```json { "meta_id": "string", "category": "string" } ``` ### Required Fields * **`meta_id`** (string): The meta\_id of the record to link to (e.g., `FE00000001`, `SE00000001`, `SH00000001`) * **`category`** (string): The category of the linked record (e.g., "Feature", "Show", "Season", "Episode") ## 2. CRUD Operations ### Create Linkages are created as part of record creation or update operations. Include the `linkage` array in your request payload: **Endpoint:** `PUT /record/{metaId}` or `POST /record/create` **Example - Creating a Feature with linkage:** ```json { "original_title": "My Feature Film", "category": "Feature", "first_release_year": 2023, "linkage": [ { "meta_id": "FE00000002", "category": "Feature" } ] } ``` **Example - Linking an existing Feature to another record:** ```json { "linkage": [ { "meta_id": "FE00000003", "category": "Feature" } ] } ``` ### Read Retrieve linkages for a record: **Endpoint:** `GET /record/{metaId}` The response includes a `linkage` array with linked records: **Example - Get Feature linkages:** ```json { "meta_id": "FE00000001", "original_title": "My Feature Film", "category": "Feature", "linkage": [ { "meta_id": "FE00000002", "link_record_id": 789, "original_title": "Another Feature", "category": "Feature", "first_release_year": 2022 }, { "meta_id": "FE00000003", "link_record_id": 101, "original_title": "Related Feature", "category": "Feature", "first_release_year": 2021 } ] } ``` **Specific Linkage Endpoints:** * `POST /record/linkage` - Get records linkage with additional data * `POST /record/linkage/full` - Get full record linkage **Example - Get linkage by category (Feature):** ```bash curl -X POST '{API_URL}/record/linkage/full' \ -H 'Content-Type: application/json' \ -d '{ "meta_id": "FE00000001", "category": "Feature" }' ``` ### Update Update linkages by including the `linkage` array in your update request: **Endpoint:** `PUT /record/{metaId}` **Example - Updating Feature linkages:** ```json { "linkage": [ { "meta_id": "FE00000004", "category": "Feature" }, { "meta_id": "FE00000005", "category": "Feature" } ] } ``` The system will automatically: * Create new linkages that don't exist * Update existing linkages * Remove linkages that are not included in the array (depending on implementation) **Example - Updating a Feature record and its linkages:** ```json { "original_title": "Updated Feature Title", "linkage": [ { "meta_id": "FE00000002", "category": "Feature" } ] } ``` ### Delete Delete linkages by either: 1. **Excluding from array**: Remove the linkage from the `linkage` array in an update request 2. **Setting deleted flag**: Include `"deleted": true` in the linkage object: **Example - Deleting a Feature linkage:** ```json { "linkage": [ { "meta_id": "FE00000002", "category": "Feature", "deleted": true } ] } ``` **Example - Removing all linkages from a Feature:** ```json { "linkage": [] } ``` **Note:** When a record is deleted, all its linkages are automatically removed. ## 3. Show Season Episode Relationship The Show → Season → Episode relationship is a hierarchical structure where: * **Show** is the top-level record * **Season** is linked to a Show * **Episode** is directly linked to both a Season and a Show * The Episode's Show linkage is **automatically managed** based on the Episode's Season relationship ### Creating the Hierarchy #### Step 1: Create the Show ```json { "original_title": "My Amazing Show", "category": "Show", "first_release_year": 2020 } ``` **Resulting meta\_id:** `SH00000001` #### Step 2: Create and Link a Season ```json { "original_title": "Season 1", "category": "Season", "linkage": [ { "meta_id": "SH00000001", "category": "Show" } ], "season_numbering": { "type": "original", "season_number": 1 } } ``` **Resulting meta\_id:** `SE00000001` #### Step 3: Create and Link an Episode ```json { "original_title": "Pilot Episode", "category": "Episode", "linkage": [ { "meta_id": "SE00000001", "category": "Season" } ], "episode_numbering": { "type": "original", "episode_number": 1 } } ``` **Important:** When you link an Episode to a Season, the system automatically: * Creates a direct linkage between the Episode and the Season's parent Show * The Episode now has **two direct linkages**: one to the Season and one to the Show * The Show linkage is automatically defined/managed based on the Season relationship ### Response Structure for Show Season Episode When retrieving a Show, Season, or Episode with linkages, the response includes: **For Show:** ```json { "meta_id": "SH00000001", "original_title": "My Amazing Show", "category": "Show", "linkage": [ { "meta_id": "SE00000001", "link_record_id": 789, "original_title": "Season 1", "category": "Season", "season_number": 1, "number_of_episodes": 10 } ] } ``` **For Season:** ```json { "meta_id": "SE00000001", "original_title": "Season 1", "category": "Season", "season_number": 1, "linkage": [ { "meta_id": "SH00000001", "link_record_id": 456, "original_title": "My Amazing Show", "category": "Show" }, { "meta_id": "EP00000001", "link_record_id": 101, "original_title": "Pilot Episode", "category": "Episode", "episode_number": 1, "season_number": 1, "show_title": "My Amazing Show", "show_meta_id": "SH00000001" } ] } ``` **For Episode:** ```json { "meta_id": "EP00000001", "original_title": "Pilot Episode", "category": "Episode", "linkage": [ { "meta_id": "SE00000001", "link_record_id": 101, "original_title": "Season 1", "category": "Season", "season_number": 1, "number_of_episodes": 10 }, { "meta_id": "SH00000001", "link_record_id": 102, "original_title": "My Amazing Show", "category": "Show" } ], "episode_number": 1, "season_number": 1 } ``` **Note:** The Episode has direct linkages to both the Season and the Show. The Show linkage is automatically created and managed based on the Season's parent Show. ### Key Features 1. **Automatic Show Linkage**: When an Episode is linked to a Season, the system automatically creates a direct linkage between the Episode and the Season's parent Show. 2. **Direct Linkages**: Episodes have direct linkages to both Season and Show in the database. The Show linkage is automatically managed based on the Episode's Season relationship. 3. **Numbering**: * Seasons use `season_number` from `season_numbering` * Episodes use `episode_number` from `episode_numbering` and inherit `season_number` from their parent Season 4. **Episode Count**: Seasons include `number_of_episodes` which counts all linked Episodes. ### Updating Show Season Episode Relationships To change an Episode's Season: ```json { "linkage": [ { "meta_id": "SE00000002", "category": "Season" } ] } ``` The system will: * Detach the Episode from the old Season * Attach the Episode to the new Season * **Automatically update** the Episode's Show linkage to match the new Season's parent Show To change a Season's Show: ```json { "linkage": [ { "meta_id": "SH00000002", "category": "Show" } ] } ``` All Episodes in the Season will automatically have their Show linkages updated to match the new Show. ### Important Constraint **An Episode should only link to 1 Season.** ## 4. FAQ
Q: Why is an Episode de-linked from both the Season and the Show when de-linking it from a Season only? Answer: The primary linkage exists between Season and Episode.\ The Show–Episode linkage is inherited through the Season. When an Episode is de-linked from a Season, the inherited Show–Episode linkage is also removed to maintain data consistency.