Documenting ItemContainerType

[ThomasPO]

If I've understood correctly, the notion of ItemContainer replaces that of FragmentInstance (at least in XML serialisation). I found it by looking at the XML schema here.

The online documentation doesn't mention this ItemContainer. It would be good to mention it.

Since the notion of Fragment disappears in DDI4, we should remove the references in the documentation here:

• DDIInstance
• as well as in the TopLevelReference element visible in the XML schema

[DanSmith]

Hi Thomas,

Yes, the ItemContainer is a direct replacement for the FragmentInstance in version 4, although its structure should be the same. It is auto generated for the XML serialization. A similar container is created for the JSON serialization. There isn't a container for the RDF serialization.

You are right, we should update the documentation and make sure these auto generated containers are properly documented. Thanks!

[duffgui]

Hi all,

I have tried to convert a DDI 3.3 file to DDI 4 JSON file validating against the JSON schema found here. I have hit a roadblock so far since it seems that the ItemContainer is not in the JSON Schema. Hence, I do not have any container to read in the Json Schema and map to the FragmentInstance.
Do you confirm that point? If so, could someone add a task to this issue?

Thanks in advance.

Guillaume

[DanSmith]

Hi Guillaume,

Good point, the json schema generator was just re-written and this may have been skipped (as the container is auto generated) so thanks for testing this out. I've added #61 to track this.

[DanSmith]

Item Container in the json schema is described #61 (comment)

[duffgui]

@DanSmith I am confused by the last version of the schema published here: https://docs.ddialliance.org/DDI-Lifecycle/dev/output/jsonSchema.json
The ItemContainer is not defined in the schema.
As noticed in the issue #61 there are still other incoherences between the JSON and XML serialisations with base "properties in JSON terms (types in XML) such as ReferenceType (cf the screenshot as an attachment).
I have checked the corresponding types in the XSD schema, they are well defined.
Thanks.

[DanSmith]

There is not an ItemContainer in the Lifecycle DDI model, it is just a packaging construct in the XML schema representation.
There is no container type in the RDF\OWL serializations.
In the JsonSchema, the Json Graph format created by Netflix's Falcor project is used. It serializes the identified items based on type and identifier. Each defined type is a hash map from their identifier (ddi urn) to the object. References are made using the same types and identifiers.

Here is an example of the json with one Variable and two Concepts that complies with the current 4.0 beta json schema.

The structure is

• Optional reference to the top level item(s)
• Hashmap of Variables
• Hashmap of Concepts

Each item type will get its own hashmap, with the keys being the DDI urn and the values being the object description as defined in the json schema.

{
  "topLevelReference": [
    {
      "$type": "ref",
      "value": ["Variable", "urn:ddi:int.example:D9295857-2600-409D-96F2-454A9443BEF4:1"]
    }
  ],
  "Variable": {
    "urn:ddi:int.example:D9295857-2600-409D-96F2-454A9443BEF4:1": {
      "$type": "Variable",
      "URN": "urn:ddi:int.example:D9295857-2600-409D-96F2-454A9443BEF4:1",
      "Agency": "int.example",
      "ID": "D9295857-2600-409D-96F2-454A9443BEF4",
      "Version": "1",
      "VariableName": [{"String": [{"MultilingualStringValue": {
                "Value": "var1",
                "LanguageTag": "en"
              }}]
        }
      ],
      "ConceptReference": [
        {
          "$type": "ref",
          "value": [ "Concept","urn:ddi:int.example:390B41A0-FB3F-4B84-8805-A7C18656F115:1"]
        },
        {
          "$type": "ref",
          "value": ["Concept", "urn:ddi:int.example:EB46DAF2-0CB7-4657-9D6A-E2A087B4A233:1"]
        }
      ]
    }
  },
  "Concept": {
    "urn:ddi:int.example:390B41A0-FB3F-4B84-8805-A7C18656F115:1": {
      "$type": "Concept",
      "URN": "urn:ddi:int.example:390B41A0-FB3F-4B84-8805-A7C18656F115:1",
      "Agency": "int.example",
      "ID": "390B41A0-FB3F-4B84-8805-A7C18656F115",
      "Version": "1",
      "ConceptName": [{"String": [{"MultilingualStringValue": {
                "Value": "Concept 1",
                "LanguageTag": "en"
              }}]}]
    },
    "urn:ddi:int.example:EB46DAF2-0CB7-4657-9D6A-E2A087B4A233:1": {
      "$type": "Concept",
      "URN": "urn:ddi:int.example:EB46DAF2-0CB7-4657-9D6A-E2A087B4A233:1",
      "Agency": "int.example",
      "ID": "EB46DAF2-0CB7-4657-9D6A-E2A087B4A233",
      "Version": "1"
      "ConceptName": [{"String": [{"MultilingualStringValue": {
                "Value": "Concept 2",
                "LanguageTag": "en"
              }}]}]
    }
  }
}

example.json

Feedback on the structure of the json schema would be much appreciated.
There are already some trade offs that I have noticed: Having one hash map per item type could add increased processing costs when streaming large sets of DDI as they would first need to be sorted by type prior to streaming/serialization. It does make end user lookup by reference type and id easier when size isn't a consideration. Perhaps we should consider a more item by item serialization instead of using the per type hashmaps?