remove the `data` dictionaries

Do you want to request a feature or report a bug?

Debt / improvement.

What’s the current behavior?

Right now many objects in Slate have a data dictionary where you can store userland metadata that Slate doesn’t need to concern itself with. This works fine for now, and with Immutable.js it’s the only reasonable way to do it.

However, once we switch to plain JSON objects, and are using an interface-based API, I think it will be better to allow userland to store metadata at the top level of any objects. For example:

{
  type: 'link',
  nodes: [...],
  url: 'https://example.com',
}

Instead of needing to nest it inside data.url, the url property can live at the top level. And the object still implements the Element interface so everything works as expected.

[cameracker]

Panicked when I read “remove data dictionaries” but the alternative sounds good.

[ianstormtaylor]

@ssalka good question! That is definitely the tradeoff here. I don’t take it lightly, but I think as I’ve been working through some of the changes for #2495 I’ve slightly changed how I think about Slate’s data model. I’ll explain how my thoughts have evolved since the original decision to keep them separate and you can see what you think…

---

Before, we’ve had three domain layers:

// This layer is the top one, and used by Slate to store the
// information it cares about.
{
  object: 'block',
  type: 'link',
  nodes: [...],
  // This layer is for the developer using Slate to add any of
  // their domain-specific information.
  data: {
    url: 'https://exmaple.com',
    external: true,
    ...
    // This layer would be if a developer wanted to allow their
    // **end users** to have a namespace where they can keep
    // their own metadata. For example, if you allowed for users
    // to configure their editor differently with a UI.
    properties: {
      ...
    }
  }
}

Up to now this has worked, since keeping them separate is guaranteed not to clash—and that is important. And for Immutable.js it’s actually required, because it can’t handle dynamic properties.

But it’s not without tradeoffs.

It adds complexity to have a nested data object, and the API for retrieving things from the nested object becomes awkward.

And when you end up serializing your data into your database, or presenting it externally to someone who has no knowledge that you use Slate, it feels weird to have the separation in where data lives, when all of it is “your” data. You likely merge the properties in your custom serialization layer, or just absorb the awkwardness (and extra data size bloat in the case that data is empty) as a cost of doing business.

Not only that, but if you are building a more advanced editor where you need the third layer of namespacing (eg. node.data.properties, but it can be named anything), the API for retrieving information from that third layer is especially awkward. And the distinction between them to end users is not clear.

---

After, we have just two domain layers:

// This layer is the top one, and it's where you add any of your
// domain-specific information. Slate only requires that the
// shape implement a minimal interface for it to operate on it.
{
  nodes: [...],
  type: 'link',
  url: 'https://exmaple.com',
  external: true,
  ...
  // This layer would be if a developer wanted to allow their
  // **end users** to have a namespace where they can keep
  // their own metadata. For example, if you allowed for users
  // to configure their editor differently with a UI.
  properties: {
    ...
  }
}

In the updated data model, Slate changes the way it thinks about the data, to being interface-based. As long as your data implements the interface it expects, you can store anything in it.

It’s kind of like Slate acting on your own custom data model instead. So instead of needing a node.data dictionary to hold dynamic properties, you can store them at the top level. But at the cost of not being able to use the special-cased nodes property.

This also unlocks possibilities that previously would have been awkward… for example storing an node.id property on each node can be kept at the top-level, instead of the awkward node.data.id, which feels weird for such a canonical property to live in a nested dictionary.

Even further, I’m experimenting with the node.type property actually living in developer-land. Slate doesn’t technically need to know about type to do its job—in fact it’s always been type-averse in not wanting to set a default for example. You could call it kind, or name, or whatever made sense for your use case. Or if you have only one type of node, you could leave it out altogether.

So the interface for nodes might just require:

// Value
{
  nodes: [...],
  selection: {...},
  annotations: {...},
}

// Element
{ 
  nodes: [...]
}

// Text
{
  text: '...',
  marks: [...]
}

---

You end up being able to describe things in a way that feels very natural when exposed to an end user of your API:

{
  type: 'link',
  url: 'https://example.com',
  nodes: [...],
}

{
  type: 'list',
  variant: 'ordered', 
  nodes: [...],
}

{
  type: 'image',
  url: 'http://example.com/image.png',
  width: 400,
  height: 300,
  nodes: [...],
}

---

We’ve also removed the need for object: 'block' or object: 'inline', since those are now part of your own Slate editor’s runtime schema configuration. For example, you could tell it to automatically treat any node with property type: 'link' as an inline.

But, without the nested data attribute, you could decide that for your data model it actually makes sense to hard-code the object property:

{
  object: 'block',
  type: 'list',
  variant: 'ordered',
  nodes: [...]
}

{
  object: 'inline',
  type: 'link',
  url: 'https://example.com',
  nodes: [...]
}