From what I've been able to gather, one of the two major use cases that WSCCI is targeting with its JSON-LD support is deployment.
I've been having a little trouble wrapping my head around how we want deployment to work. In this post, I lay out my understand of how it could work, some of which exploits the Linked Data part of JSON-LD. I'm hoping that those involved in developing deployment can help me understand if/where I've got it wrong.
I've drawn this up as a UML activity diagram, with different streams for the following actors (left to right):
- Site admin on Source Site
- Drupal instance on Source Site
- Drupal instance on Target Site
- Site admin on Target Site
If you can't read activity diagrams, I've written out a translation below, or you can take a look at Agile Modeling for a quick explanation of the notation.
The admin on the source site creates a deployment set, and the system creates a URL for it. The admin can then go to the importing (or "target") site and enter that URL. The target site will then go to that URL to get a list of entity URIs.
The target site will then iterate through the entity URIs to add each entity. It starts by seeing if it already has the JSON-LD for the entity in its cache (this could happen in the case of entity references). If it doesn't, it gets the JSON-LD from the source site. Once it has this, it will see whether there is already a corresponding entity in the system. If there isn't, then it creates one.
Once the entity is loaded/created, add the fields. I leave this to be detailed in a future diagram because there are a lot of separate discussions that need to happen around that.
Once all the fields are added, the entity's URI is removed from the queue. Once the queue is empty, the cache of serializations from the source site is also emptied.
Discussion/Confirmation needed from deployment developers
There are a few points which I want to draw attention to.
- Deployment sets
Basically, this is the entity part of deployment plans. It's a set of URIs that should be imported/updated. I would see three ways of creating these
- Manually, by checking off the entities via a UI
- Automatically, by adding all entities of a certain type
- via Queryable API, allowing the target site to pass in parameters like "updated since DATETIME"
Does this make sense?
- Matching entities from source to target
- We need to consider how we are going to handle this... specifically, whether we are going to have the UUID in the URI and then parse it out or whether we just store the full URI from the source site and matching based on that. I lean towards storing the source's full URI.
- Dependencies between entities
When using entity reference fields, you don't just need the content from the entity itself, but you also need the content from the referenced entities. This would take place in the "Add/Update entity's field values" part of the process (which I haven't diagramed yet).
Since we're using Linked Data, I would suggest that, in the JSON-LD serialization of an entity, the entity's reference fields only contain the URIs for the referenced entities (and possibly the title field value). That URI can then be added to the import queue and used to retrieve the rest of the data about the referenced entity.