How is 'lid' actually used? The 1.1 spec says nothing about this about json-api

[gabesullice]

Hi @cmeeren, thanks for the question. The lid member has a very limited use-case in the base specification. It is only useful to create self-referential resources when client-generated UUIDs are not convenient/permitted. E.g.

{
  "data": {
    "type": "person",
    "lid": "foo",
    "attributes": {
      "name": "Sam Solipsist"
    },
    "relationships": {
      "me": {
        "data": {
          "type": "person",
          "lid": "foo"
        }
      }
    }
  }
}

That said, your spidey-sense is correct. lids are useful for creating more than one resource in a request. However, there is no official way to do so via the included member (a.k.a. "sideposting"). The recommended method is to implement the atomic extension.

If you do implement that extension, we would love to hear about it!

[cmeeren]

Thanks for the clarification!

[jelhan]

@cmeeren Your main motivation is supporting bulk creation, isn't it? I have written an extension addressing that use case some time ago. Your comment reminded me to publish it. Please find it here: https://github.com/jelhan/json-api-bulk-create-extension

I consider it a first draft. Would love to get feedback on it. Please use GitHub issues of that repository for it.

[jelhan]

Could this be implemented using a profile instead of an extension?

No. Profiles cannot define specification semantics. But that's needed to define bulk creation.

the spec does not prohibit included in resource creation request bodies

That might be true taking it by word. But it's definitely against the intention. And it does not define how to process that. It would likely cause compatibility issues trying to use included member within document used with a create request. Also I don't see what benefit that would provide over using an extension.

I think we should improve wording to explicitly forbid included in documents used for creating, updating and deleting resources.

[cmeeren]

To be clear, I would appreciate just a quick clarification on this so I can start implementing support for sideloading/sideposting in my JSON:API framework.

For example, is this a valid resource creation request that will create an order along with a customer?

{
  "data": {
    "type": "order",
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "lid": "d4524641-13bf-4c36-b681-2e91e0c83754"
        }
      }
    }
  },
  "included": [
    {
      "type": "customer",
      "lid": "d4524641-13bf-4c36-b681-2e91e0c83754",
      "attributes": {
        "name": "John Doe"
      }
    }
  ]
}

And if client-generated IDs are supported for customer, would it be valid to use id instead of lid above?

[cmeeren]

I have briefly looked at the atomic extension and find that it seems to be too complicated to be worth implementing it for my use-cases. I simply want to create several resources in one operation, without having to deal with transactional consistency across an ordered array of generic operations that can include patch, delete, etc. I therefore can't see myself implementing that extension anytime soon. It would be great if the base spec could support sideposting, which is a much simpler use-case (kind of the simplest special case of atomic, I think).

[jelhan]

I have briefly looked at the atomic extension and find that it seems to be too complicated to be worth implementing it for my use-cases. I simply want to create several resources in one operation, without having to deal with transactional consistency across an ordered array of generic operations that can include patch, delete, etc.

Sounds as if you would be interested in a bulk or sideposting extension. Some work on such an extension has already been started in #1380.

There is no reason for not having both the Atomic Operations extension and a Sideposting extension in parallel.

I think it's unlikely that it will be added to base specification any time soon. Extensions well cover that use case while keeping the base spec slim.

[cmeeren]

Thanks, I'll check it out. I can certainly live with a simpler extension that only covers my use-case and does not impose much additional implementation overhead.

Extensions well cover that use case while keeping the base spec slim.

Since you mention it: What is actually the rationale for adding new versions of the base specification now that extensions are a thing? Couldn't conceivably almost everything one would need, be added as an extension? What belongs in the base spec going forward?

[jelhan]

What is actually the rationale for adding new versions of the base specification now that extensions are a thing? Couldn't conceivably almost everything one would need, be added as an extension? What belongs in the base spec going forward?

I haven't discussed with other editors yet. Please understand the following only as my personal opinion.

Further development of the base specification should be focused on removing blockers for

1. extending the base spec using extensions,
2. further specifing aspects the base spec is agnostic about using profiles, and
3. combining the spec with other standards

The base spec itself should stay lean.

I think this is also how v1.1 was developed. Instead of adding support for the various features requested to base specification itself, implementations were unblocked to adding the features themselves.

[cmeeren]

I have taken a look at the spec, and I believe what I ask in my previous comment could be implemented as a very simple profile. I base this on the fact that, as far as I can tell, the spec 1) does not define processing rules for lid that conflict with my suggestion, and 2) the spec does not prohibit included in resource creation request bodies (it only requires data to be present).

Do you agree with my reasoning, or have I missed something?

[cmeeren]

Thanks, I'll take a look! In any case, my question from the last comment still stands: Could this be implemented using a profile instead of an extension?

[lode]

I was reading the bulk extension and wondering how lid is supposed to be used.

There a resource in the extension's primary data (bulk:data) uses lid to reference a resource in the extension's included data (bulk:included).

I was wondering if the primary data needs an extension's prefix (bulk:data). Since the lid usage in there is perfectly valid according to the base specification. The only reason I can think of needing the extension prefix is that the lid doesn't link to anywhere without the extension / the extension's bulk:included.

In other words; could the bulk extension be changed to use regular data together with bulk:included while using lid to reference between those? I would prefer if this would be allowed, since the primary data can then be 'protected' by the rules of the base specification without the extensions having to say anything about that. Plus, it can easier work together with other extensions and profiles.

(@jelhan I'm not sure if you want to change the bulk in this way, but my question is also more generic for other extensions.)

[jelhan]

There a resource in the extension's primary data (bulk:data) uses lid to reference a resource in the extension's included data (bulk:included).

I was wondering if the primary data needs an extension's prefix (bulk:data). Since the lid usage in there is perfectly valid according to the base specification. The only reason I can think of needing the extension prefix is that the lid doesn't link to anywhere without the extension / the extension's bulk:included.

Using bulk:data and bulk:included was not motivated by lid (only). I was mainly concerned that the extension may lessen or remove processing rules defined by the base specification for compound documents having a resource collection as primary data. But you may be true that this is actually not the case. I created an issue in the JSON:API bulk create extension GitHub project to investigate further: jelhan/json-api-bulk-create-extension#8