Protocol

Protocol examples

Protocol basics

• The ZeroMQ protocol should not assume any shared state between the client and the server
• Communications between the client and the Midgard Daemon should happen asynchronously
• Midgard objects are represented using JSON-LD
• In addition to the regular Midgard payload, I/O calls may include a context object that can associate that call with a midgard_user and possibly a workspace. The user key there basically holds whatever is to be given to the midgard_user class when instantiating
• Normal I/O (saving objects, making queries) should follow ZeroMQ request/response protocol
• Signals (notifications about I/O events) should follow ZeroMQ subscribe/publish protocol

Note: this implementation is very similar to how VIE and Midgard Create handle their content. This should make it easy to integrate Midgard daemon services to any rich front-end.

Write request:

update: {
   '#': {
       mgd: 'http://www.midgard-project.org/midgard2/10.05',
       dcterms: 'http://purl.org/dc/terms/'
   }
   '@': '<urn:uuid:e37f86e23b3911e09325618cb7e066d466d4>',
   a: 'mgd:midgard_article',
   'dcterms:title': 'Foo'
}
context: {
   user: {
      login: 'admin',
       password: 'password'
   },
   workspace: '/live/drafts'
}

##Response:

status: {
   code: -0,
   error: MGD_ERR_OK
}

(see list of Midgard Error codes)

Query request:

query: {
   '#': {
       mgd: 'http://www.midgard-project.org/midgard2/10.05',
       dcterms: 'http://purl.org/dc/terms/'
   }
   'a': 'mgd:midgard_article',
   constraints: [
       {
           'dcterms:title',
           'LIKE',
           'Fo%',
       }
   ],
   order: [
       {
           'dcterms:created': 'desc'
       }
   ]
}
context: {
    workspace: '/live'
}

Note: when making queries, the workspace key in context limits the query to that workspace only. Key workspacetree limits the query to that workspace and its parents.

Response:

response: [
    {
       '#': {
           mgd: 'http://www.midgard-project.org/midgard2/10.05',
           dcterms: 'http://purl.org/dc/terms/'
       }
       '@': '<urn:uuid:e37f86e23b3911e09325618cb7e066d466d4>',
       a: 'mgd:midgard_article',
       'dcterms:title': 'Foo'
   }
]

Connecting to a signal:

sub: {
   '#': {
       mgd: 'http://www.midgard-project.org/midgard2/10.05'
   }
   a: 'mgd:midgard_article',
   guid: null, // Any article object
   signal: 'action-created'
}

Mapping Midgard objects to RDF/JSON-LD

• GUIDs should be used through <urn:uuid:GUID> URIs
• MidgardCR supports RDF natively and provides the necessary namespace management utilities for JSON-LD to be mapped to Midgard storage seamlessly
• With Midgard2 we need to handle this in a more manual way. There are two ways to go about this:

RDF mapping without ontology

In case of a regular MgdSchema that doesn't have any ontology mappings, we should use a mgd namespace to map between RDF and the normal Midgard types and properties. This means that:

• mgd:midgard_person maps to the midgard_person type
• mgd:firstname maps to the firstname property of the class

RDF mapping with ontology

Midgard Create introduced a simple way to map a MgdSchema type and its properties to a RDF ontology.

<Schema xmlns="http://www.midgard-project.org/repligard/1.4">
    <type name="org_midgardproject_news_article" table="org_midgardproject_news_article">
        <user_values>
            <typeof>http://rdfs.org/sioc/ns#Post</typeof>
            <namespaces>sioc:http://rdfs.org/sioc/ns#,dcterms:http://purl.org/dc/terms/</namespaces>
        </user_values>
        <property name="title" type="string">
            <description>Title of the article</description>
            <required>true</required>
            <property>dcterms:title</property>
        </property>
        ...
    </type>
</Schema>

In this example the org_midgardproject_news_article type would map to the sioc:Post type, and title property would map to dcterms:title.