Introduction

Requirements

Definition in the Schema

yuuvis® Momentum offers a property type for the storage of structured data in JSON format. Thus, it is possible to store interleaved data structures in a queryable way without defining each single sub-property in the schema. The structured data properties should NOT be considered to replace the concept of a well-defined schema. They should be used only if the handling of objects' metadata via the conventional property definitions is not reasonable. Especially, if the structure of metadata and/or the availability of properties differs a lot for the individual object instances, the schema might grow up to a really long list of scarcely used properties. This can be avoided by the usage of a property field that can store a JSON structure as value. In this tutorial, the registration information of media in a library is considered an example use case. For this purpose, the set of information for each medium is provided in JSON structure following the concept of BibJSON.

Requirements

This tutorial is dedicated to experienced users. Please find information on requirements, maven and client configuration in our "Importing Documents via Core API" tutorial, on which the variables' names are based. The handling of any IOException is demonstrated there, too.

Definition in the Schema

In the context of the library example, the below displayed app schema is used that contains two property definitions and one object type definition referencing the properties. The first property bibjsonsample:bibjson has the property type structureddata. This property will be used for the storage of the BibJSON structure containing the registration information of the corresponding medium. The second property bibjsonsample:locations allows for the assignment of a list of strings indicating storage locations if a printed version is available for the corresponding medium. In the object type definition of bibjsonsample:medium, both properties are referenced. Additionally, a binary content file can be assigned if necessary.

<?xml version="1.0" encoding="utf-8"?>
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v5.0/ dmsCloud-schema.xsd">

    <propertyStructuredDataDefinition>
        <id>bibjsonsample:bibjson</id>
        <description>field for the BibJSON structure identifying and describing the medium</description>
        <propertyType>structureddata</propertyType>
        <cardinality>single</cardinality>
        <required>false</required>
    </propertyStructuredDataDefinition>
    <propertyStringDefinition>
        <id>bibjsonsample:locations</id>
        <description>field for storage locations of printed versions of the medium</description>
        <propertyType>string</propertyType>
        <cardinality>multi</cardinality>
        <required>false</required>
    </propertyStringDefinition>
    <typeDocumentDefinition>
        <id>bibjsonsample:medium</id>
        <baseId>system:document</baseId>
        <propertyReference>bibjsonsample:bibjson</propertyReference>
        <propertyReference>bibjsonsample:locations</propertyReference>
        <contentStreamAllowed>allowed</contentStreamAllowed>
    </typeDocumentDefinition>

</schema>

...

/schema>

Specify Values during Import

Two example objects will be created as instances of the object type abbBibjsonsample:medium. Both of them get a BibJSON value for the property appbibjsonsample:bibjson assigned to them.

The first object is a book. In addition to the bibliographic information stored in the property appbibjsonsample:bibjson, two storage locations for printed versions are specified.

{
  "objects": [{
    "properties": {
      "objectTypeId": {
        "value": "appBibjsonsample:medium"
      },
      "appBibjsonsample:bibjson": {
        "value": {
          "type": "book",
          "title": "My Book Title",
          "author": [
            {"name": "Heinrich Schuetzel"Sturz, Maximilian},
            {"name": "Maximilian Sturz"}
          ],
          "year": "1995",
          "owner": "My Library",
          "id": "ID_of_book",
          "url": "http://mylibrary.com/ebooks/ID_of_book36513466534",
          "publisher": "Example Verlag Mustershagen",
          "edition": {
            "number": 2,
            "language": "English"
          },
          "identifier":[
            {
              "id": "0002-9327",
              "type": "issn"
            }
          ]
        }
      },
      "appBibjsonsample:locations": {
        "value": [
          "central library, CN-3214-5324",
          "branch library east, 43-654b"
        ]
      }
    }
  }]
}

The second object is a collection of articles without corresponding printed versions.

{
  "objects": [{
    "properties": {
      "objectTypeId": {
        "value": "appBibjsonsample:medium"
      },
      "appBibjsonsample:bibjson": {
        "value": {
          "metadata": {
            "collection": "ym_concepts",
            "label": "yuuvis(R) Momentum Core Concepts",
            "description": "Documentation for yuuvis(R) Momentum Core in a structured, theoretical way, with links to the tutorial section.",
            "id": "ID_of_collection",
            "owner": "OS",
            "created": "2020-06-09T15:04:12.944771",
            "modified": "2021-06-10T11:05:17.166993",
            "source": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/-4BkAg",
            "records": 2
          },
          "records": [
            {
              "collection": "ym_concepts",
              "type": "article",
              "title": "Schema - Defining Object Types",
              "id": "ID_of_schema_article",
              "link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/AYFkAg",
              "author":[
                {"name": "Heinrich Schuetzel"},
                {"name": "George Trader"},
                {"name": "Johann Fluss"}
              ],
              "created": "2020-06-09T15:04:12.944771",
              "modified": "2021-06-10T08:53:23.532949"
            },
            {
              "collection": "ym_concepts",
              "type": "article",
              "title": "Search Query Language",
              "id": "ID_of_query_article",
              "link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/gIFkAg",
              "author":[
                {"name": "Andrea Schumann"},
                {"name": "Franz Lissner"},
                {"name": "Hans Kammer"},
                {"name": "Johann Fluss"}
              ],
              "created": "2020-06-16T14:03:01.833660",
              "modified": "2021-06-02T09:54:12.643040"
            }
          ]
        }
      }
    }
  }]
}

The successfully executed import returns the entire sets of metadata for each object, enriched with the system properties.

{"objects":[{"properties":{"system:objectId":{"value":"4e6907ae922a27ba-ea72f478-439d4fa6-a2f6b94c-33fbbee5adde19d42d46e13a"},"system:baseTypeId":{"value":"system:document"},"system:objectTypeId":{"value":"appBibjsonsample:medium"},"system:createdBy":{"value":"275c826c-6a61-4e89-9512-8d935a1631e5"},"system:creationDate":{"value":"2021-06-11T1114T12:4146:0032.230Z870Z"},"system:lastModifiedBy":{"value":"275c826c-6a61-4e89-9512-8d935a1631e5"},"system:lastModificationDate":{"value":"2021-06-11T1114T12:4146:0032.230Z870Z"},"system:versionNumber":{"value":1},"system:tenant":{"value":"default"},"system:traceId":{"value":"c143d4b235273f7b1f5715bec164414a"},"appBibjsonsample:bibjson":{"value":{"type":"book","title":"My Book Title","author":[{"name":"Heinrich Schuetzel"Sturz, Maximilian},{"name":"Maximilian Sturz"}],"year":"1995","owner":"My Library","id":"36513466534ID_of_book","url":"http://mylibrary.com/ebooks/36513466534","publisher":"Example Verlag Mustershagen","edition":{"number":2,"language":"English"},"identifier":[{"id":"0002-9327","type":"issn"}]}},"appBibjsonsample:locations":{"value":["central library, CN-3214-5324","branch library east, 43-654b"]}}}]}
{"objects":[{"properties":{"system:objectId":{"value":"bbdfb9e3c442cffc-c192e555-4378443c-936d9573-9101a0fd8cc07f825847833a"},"system:baseTypeId":{"value":"system:document"},"system:objectTypeId":{"value":"appBibjsonsample:medium"},"system:createdBy":{"value":"275c826c-6a61-4e89-9512-8d935a1631e5"},"system:creationDate":{"value":"2021-06-11T1114T12:4146:0033.490Z330Z"},"system:lastModifiedBy":{"value":"275c826c-6a61-4e89-9512-8d935a1631e5"},"system:lastModificationDate":{"value":"2021-06-11T1114T12:4146:0033.490Z330Z"},"system:versionNumber":{"value":1},"system:tenant":{"value":"default"},"system:traceId":{"value":"6cc8bad490501a399ece9caad9169a31"},"appBibjsonsample:bibjson":{"value":{"metadata":{"collection":"ym_concepts","label":"yuuvis(R) Momentum Core Concepts","description":"Documentation for yuuvis(R) Momentum Core in a structured, theoretical way, with links to the tutorial section.","id":"cdc7095f-a5ce-486d-92a7-6d0955d969eeID_of_collection","owner":"OS","created":"2020-06-09T15:04:12.944771","modified":"2021-06-10T11:05:17.166993","source":"https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/-4BkAg","records":2},"records":[{"collection":"ym_concepts","type":"article","title":"Schema - Defining Object Types","id":"569bbbf7-7163-4541-9921-d2fa2d82be02ID_of_schema_article","link":"https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/AYFkAg","author":[{"name":"Heinrich Schuetzel"},{"name":"George Trader"},{"name":"Johann Fluss"}],"created":"2020-06-09T15:04:12.944771","modified":"2021-06-10T08:53:23.532949"},{"collection":"ym_concepts","type":"article","title":"Search Query Language","id":"122bed86-32c6-4ef8-8362-001d2066a97aID_of_query_article","link":"https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/gIFkAg","author":[{"name":"Andrea Schumann"},{"name":"Franz Lissner"},{"name":"Hans Kammer"},{"name":"Johann Fluss"}],"created":"2020-06-16T14:03:01.833660","modified":"2021-06-02T09:54:12.643040"}]}}}}]}

Search Queries

...

The individual sub-fields within the JSON value for the property appbibjsonsample:bibjson are queryable. In this chapter, some example search queries are explained.

All objects of type medium.

Code Block
language sql
SELECT system:objectId* FROM appBibjsonsample:medium WHERE

Return only the bibjson value

Code Block
language sql
SELECT appBibjsonsample:bibjson.id = 'ID_of_book'

...

FROM appBibjsonsample:medium

Return only parts of the bibjson value

Code Block
language ymlsql
{ "objects":[ { "properties":{ "system:objectId":{ "value":"4e6907ae-ea72-439d-a2f6-33fbbee5adde" } } } ], "numItems":1, "hasMoreItems":false, "totalNumItems":1 } SELECT appBibjsonsample:bibjson.title,appBibjsonsample:bibjson.author[1].name,appBibjsonsample:bibjson.metadata.id FROM appBibjsonsample:medium

If the path is unknown, a '*' wildcard can be used.

Code Block
language sql
SELECT appBibjsonsample:bibjson.metadata.id FROM appBibjsonsample:medium WHERE appBibjsonsample:bibjson.* = 'ID_of_schema_article'

Search within a list and usage of CONTAINS

Code Block
language sql
SELECT appBibjsonsample:bibjson.title FROM appBibjsonsample:medium WHERE appBibjsonsample:bibjson.author[*].name CONTAINS('Sturz')

Search within the records of collections

Code Block
language sql
SELECT appBibjsonsample:bibjson.records.title,appBibjsonsample:bibjson.metadata.id FROM appBibjsonsample:medium WHERE appBibjsonsample:bibjson.records[*].created IN LASTYEAR()

Summary