Documentation Request: More Examples Needed for Linking Custom Models to Default Modules (e.g., ProductVariant)

[lst97]

I'm writing to suggest enhancing the official documentation regarding module linking, specifically by adding more examples for scenarios where custom models need to be linked to default Medusa modules, such as the ProductVariant which related to Product module.

As a new Medusa user, I recently encountered difficulties while trying to create a one-to-one relationship between a custom model (VariantSpecification) and the built-in ProductVariant model in Medusa v2. My goal was to extend the ProductVariant model with additional specifications in a separate table.

According to the current documentation on Data Model Relationships (Link - Medusa v2 Documentation), the examples primarily focus on linking two custom tables. This made it challenging to understand how to correctly link to a default Medusa module like ProductVariant.

In a recent community discussion, I asked for clarification on this topic:

Summary of the Question:

I was trying to establish a one-to-one relationship between my custom VariantSpecification model and Medusa's default ProductVariant. I was encountering an error and was unsure about the correct approach and entity name for ProductVariant when defining the link. Likewise, I initially attempted to define a relationship within my model using model.belongsTo, mimicking examples for same-module relationships, but this led to errors.

Summary of the Answer:

A community member, Ranjith, provided a very helpful and detailed explanation. Ranjith clarified that when linking models from different modules using remote links, defining explicit relationships within the model file (like model.belongsTo) is unnecessary. The relationship is instead defined solely through the defineLink function.

Ranjith provided clear code examples demonstrating how to use defineLink for one-to-one, one-to-many, and many-to-many relationships. Crucially, they provided a concrete example of how to correctly link a custom Specification model to the ProductVariant module, including:

The corrected Specification model definition (without model.belongsTo).
The defineLink implementation for linking ProductVariant and Specification.
Code snippets for creating specification and link instances.
An example of how to query and retrieve the linked data using GraphQL.
A sample JSON output illustrating the structure of the linked data.

This detailed answer significantly clarified the process and provided a working solution for linking to default Medusa modules.

Request:

I believe that incorporating examples similar to Ranjith's answer into the official Medusa documentation would be extremely beneficial for new users. Specifically, adding examples that demonstrate linking custom models to default modules like ProductVariant would greatly improve the documentation's clarity and usability. This would help users quickly understand and implement module linking in more complex, real-world scenarios.

Link to the discussion: Answer

[shahednasser]

Hi @lst97 thank you for your feedback! Did you try checking out the Module Links documentation? It showcases how to define a link to the Product Module. There's also the Extend Product Module guide that demonstrates the steps to extend the Product data model (which you can apply to variants as well)

Would love to understand the difficulties you had with these documentations in order for us to improve it.