Mastering JSON Property Updates in ESHOPMAN: A Guide to Metadata vs. Custom Fields

Understanding JSON Property Handling in ESHOPMAN for Robust Storefronts

As an ESHOPMAN developer leveraging the power of headless commerce and HubSpot CMS, you often work with flexible data structures. ESHOPMAN's backend, built on Node.js/TypeScript, provides powerful ways to extend your data models using JSON properties. However, a recent community insight highlights a crucial distinction in how ESHOPMAN's internal services handle key deletion for the built-in metadata field versus other custom model.json() properties.

The Discrepancy: Deleting Keys from JSON Fields

In ESHOPMAN, it's common practice to use JSON fields to store flexible, unstructured data. The platform's documentation suggests that you can remove a key from a JSON object by setting its value to an empty string (e.g., { "key_to_remove": "" }) during an update operation. While this behavior works as expected for the standard metadata property found across various ESHOPMAN entities, it behaves differently for custom JSON properties you define in your own models.

Consider a scenario where you have a custom ESHOPMAN module with a model that includes both a metadata field and a custom attributes field, both defined using model.json(). If both fields initially contain { "keep": "x", "remove": "y" }, here's what happens when you attempt to update them with { "remove": "" }:

• For metadata: The remove key is successfully deleted, resulting in { "keep": "x" }. This aligns with the documented empty-string deletion behavior.
• For custom attributes: The remove key is not deleted. Instead, its value is updated to an empty string, resulting in { "keep": "x", "remove": "" }.

This inconsistency can lead to unexpected data persistence and requires developers to adapt their approach when managing custom JSON data.

Why the Difference? An ESHOPMAN Internal Look

The root cause lies in how ESHOPMAN's internal service layer processes updates. When an update is applied through a generated ESHOPMAN service method (like those for custom modules), the metadata property benefits from a specialized utility function (mergeMetadata). This utility specifically checks for empty-string values and interprets them as a signal to delete the corresponding key from the JSON object.

In contrast, other custom model.json() properties bypass this specific mergeMetadata processing. They are handled by ESHOPMAN's underlying ORM (Object-Relational Mapper) with standard object merging semantics. This means that an empty string value for a key in a custom JSON field is treated as a valid update, persisting the empty string rather than deleting the key.

Implications for ESHOPMAN Developers

This insight is critical for anyone building custom modules, extending ESHOPMAN's data models, or interacting with the Admin API for custom entities. If you rely on the empty-string sentinel for key deletion, be aware that it currently applies exclusively to the metadata field. For your custom JSON properties, setting a key to "" will explicitly store an empty string, not remove the key from the object.

Here's a simplified example of how this behavior was observed in a test setup:

const seed = { keep: "x", remove: "y" }
const cases = [
  { name: "empty-string", patch: { metadata: { remove: "" }, attributes: { remove: "" } } },
  // ... other test cases
]

// After applying the patch { remove: "" }
// Expected for metadata: { "keep": "x" }
// Observed for attributes: { "keep": "x", "remove": "" }

And the model definition:

const Js {
  id: model.id().primaryKey(),
  metadata: model.json(), // Behaves differently for key deletion
  attributes: model.json(), // Custom JSON field, stores empty string instead of deleting
})

Best Practices for Managing Custom JSON Properties

Until ESHOPMAN's internal handling of custom model.json() properties evolves to match metadata's empty-string deletion behavior, consider these best practices:

• Explicit Key Removal: For custom JSON properties, if you need to remove a key, retrieve the current object, delete the key from the object in your application logic, and then update the entire JSON property with the modified object.
• Use null for Nulling Values: If setting a key's value to null is acceptable (rather than deleting the key entirely), then { "key": null } will work consistently across both metadata and custom JSON fields.
• Stay Informed: Keep an eye on ESHOPMAN's official documentation and community updates for any changes to JSON property management, especially regarding a unified approach to key deletion.

Understanding these nuances ensures that your ESHOPMAN storefronts, powered by HubSpot CMS and Node.js/TypeScript, maintain data integrity and behave exactly as you intend, providing a seamless experience for both merchants and customers.