Add Embedded Refract serialization

[smizell]

Proposal for thinking about a new serialization format.

[smizell]

I also wanted to point out that I'm interested in this for the sake of adding hypermedia to existing JSON structures.

{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    {
      "id": 2,
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}

becomes:

{
  "users": [
    {
      "refract": {
        "element": "resource",
        "attributes": {
          "rels": ["user"],
          "href": "/users/1"
        }
      },
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    {
      "refract": {
        "element": "resource",
        "attributes": {
          "rels": ["user"],
          "href": "/users/2"
        }
      },
      "id": 2,
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}

Or without the transcluded data:

{
  "users": [
    {
      "refract": {
        "element": "resource",
        "attributes": {
          "rels": ["user"],
          "href": "/users/1"
        }
      }
    },
    {
      "refract": {
        "element": "resource",
        "attributes": {
          "rels": ["user"],
          "href": "/users/2"
        }
      }
    }
  ]
}

[danielgtaylor]

Is there any guidance on how to handle name collisions? What would be the expected behavior of an implementation that could not produce this serialization because of a pre-existing refract property?

[smizell]

Hmm, I'm not sure exactly. We could make it less likely to collide, like with _refract?

[pksunkara]

I wanted to propose _refract. I really don't like refract. It feels like we are taking away user's freedom. But using _refract diminishes it a bit.

[smizell]

I will change to _refract then. Works for me!

[danielgtaylor]

This is definitely an interesting idea. I like the concept, but we should make sure it isn't too confusing.

In my opinion this also raises the question of which formats should be supported by a given implementation and whether the spec can provide some guidance on that issue.

[smizell]

@danielgtaylor My hope would be that you could add Refract to existing JSON, especially adding hypermedia to non-hypermedia structures. It would be very similar to JSON-LD, but a lot more powerful in that you could do lots of different types and stuff.

Regarding implementations, I would like to see this kind of stuff be a plugin for minim or some added on library. So we could keep the full version as the default, then include these other formats with use. It would go through all base types and add methods for toWhatever or however we wanted to do it.

[pksunkara]

I don't think we should do this.

[smizell]

I agree now :)

https://github.com/refractproject/rfcs/pull/14/files#r38401396

[pksunkara]

Just one issue I am having concerns about. Embedded refract is a good thing. But embedded refract in refract element? How deep does the rabbit hole go?

[smizell]

Comments addressed:

• Fixed typos
• Changed to _refract

[pksunkara]

@smizell Continuing the discussion here.

Is your concern the recursion?

It's not about the recursion. It's not about the implementation or anything. It's about concepts. It's more about the fact that refract is a core thing and embedded refract is concept built on it. What use is there for embedded refract to be in refract? Refract already allows elements in refract. If we try to use embedded refract in refract, it does nothing different except maybe add an extra nested level of object.

[smizell]

It actually does add something in that you know what has or has not been refracted. It tells you more that normal refract. No need for element specific code such as we have in Minim.

See https://github.com/refractproject/minim/blob/master/lib/primitives/base-element.js and convertAttributesToElements.

I'm ok with not including it, but I do think you actually could gain a lot.

[pksunkara]

From your example

{
  "_refract": {
    "element": "object",
    "meta": {
      "id": "bowler-103"
    },
    "attributes": {
      "foo": {
        "_refract": {
          "element": "string",
          "content": "baz"
        }
      }
    }
  },
  "first_name": "John"
}

If we don't use embedded refract in refract, this is how the example looks.

{
  "_refract": {
    "element": "object",
    "meta": {
      "id": "bowler-103"
    },
    "attributes": {
      "foo": {
        "element": "string",
        "content": "baz"
      }
    }
  },
  "first_name": "John"
}

I don't see any benefit in the first example when compared to the second one. Actually the extra _refract makes it more complex.

I do think you actually could gain a lot.

Can you give me a small example? Maybe I am having problems visualising it.

[smizell]

Well, let's use your example first.

{
  "_refract": {
    "element": "object",
    "meta": {
      "id": "bowler-103"
    },
    "attributes": {
      "foo": {
        "element": "string",
        "content": "baz"
      }
    }
  },
  "first_name": "John"
}

How would a client know that foo has been refracted? You would need some domain-specific, out-of-band knowledge to know it. The only other option is to say that "You MAY determine an object is refracted by looking for the presence of an element." But we don't want that.

So, we can get around it by treating the value of attributes as a normal object, and allow the already-reserved _refract property to tell the parser it has already been refracted.

{
  "_refract": {
    "element": "object",
    "meta": {
      "id": "bowler-103"
    },
    "attributes": {
      "foo": {
        "_refract": {
          "element": "string",
          "content": "baz"
        }
      }
    }
  },
  "first_name": "John"
}

In this example, the parser would see _refract and know it's already refracted without any other knowledge.

---

The benefit here is that you can have refracted elements mixed into the attributes tree anywhere, just like with a normal object. It would require no out-of-band knowledge or special parsing instructions like this.

[pksunkara]

Understood now. Thanks 😄