Solis

Solis means 'the sun' in Latin or just Silos spelled backwards. A simple idea to use SHACL to describe models and API on top of a data store.

Status

Although I'm using it in production I must shamefully acknowledge that it actually needs refactoring. Solis is currently still grown organically driven by my needs and understanding of problem domain(RDF, triples, ...). When my current project is live I'll start to refactor the code and release it as 1.0.

From Google Sheets to RDF, Shacl, ... to API

The biggest hurdle when developing a model is the communication between the people who know the problem domain and the developers. Next to this every change in the model has a direct impact on everything that uses the model. From migrations to documentation and eventually the API. This is an effort to streamline and minimalize this impact.

config.yml

Config file contains all the options needed to run Solis.

:debug: false
:key: your_Google_API_key
:solis:
    :cache: tmp/cache
    :query_cache_expire: 300
    :shacl: /path/to/t_shacl.ttl
    :env:
        :graph_name: https://t.example.com/
        :graph_prefix: t
        :sparql_endpoint: http://127.0.0.1:8890/sparql
        :inflections: /path/to/t.json
        :language: nl
:sheets:  
  :t: 1vi2U9Gpgu9mA6OpvrDBWRg8oVKs6Es63VyLDIKFNWYM

debug: extra logging like generated queries etc.
key: Google API key used to read a Google Sheet
solis: runtime configuration
- cache: Google Sheets can be cached to minimize Google API calls
- query_cache_expire: time construct queries should expire. 0 is never expire
- shacl: location of the shacl file to use
- env: shacl info
  - graph_name: uri of the graph
  - graph_prefix: uri prefix of the graph
  - sparql_endpoint: uri to connect to the data store. Currently focus is on triple stores
  - inflections: singular, plural mapping file for multi lingual data models
  - language: default language strings are stored in.
sheets: list of models
- t: an example sheet

Solis Model Template

This is simple template exclusively used for testing.

Google Sheet model

Tabs

_PREFIXES: a list of ontologies and prefixes used
- Base: All entities defined under this URI. Selected by '*'
- Prefix: prefix of ontology
- URI: URI of ontology
_METADATA: description fields for metadata
- key: identifier of metadata
- value: metadata value
_ENTITIES: a list of entities(classes) used in the model
- Name: name of entity
- NamePlural: plural name of entity. The generated API has RESTful endpoints. Non english entities are incorrectly pluralized
- Description: purpose of entity
- subClassOf: internal entity reference. Entity you want to inherit from
- sameAs: External entity reference (not activily used, yet)
Any number of tabs describing properties of an entity. See below

Entity tabs

Not every entity described in _ENTITIES needs a tab.

CodeTable

This is a base entity were other entities that fit a code table are inherited from

Name	Description	Min	Max	sameAs	datatype
id	unique record identifier	1	1	schema:identifier	xsd:string
short_label	lookup key, short label	0	1	xsd:string
label	prefered display label	1	1	xsd:string

Skill

Inherits from CodeTable no tab is needed. Skills a teacher can teach

[
  { "id": 1, "short_label": "problemsolv", "label": "Applying and problem-solving"},
  { "id": 2, "short_label": "commexp", "label": "Communicating and expressing"},
  { "id": 3, "short_label": "intcon", "label": "Integrating and connecting"},
  { "id": 4, "label": "Reasoning"}
]

Person

Base class for a person

Name	Description	Min	Max	sameAs	datatype
id	unique record identifier	1	1	schema:identifier	xsd:string
first_name	Person's first name	1	1	schema:givenName	xsd:string
first_name	Person's last name	1	1	schema:familyName	xsd:string

Teacher

Inherits all fields from Person and adds extra property "skill" an extra tab with the extra properties must exist

Name	Description	Min	Max	sameAs	datatype
id	unique record identifier	1	1	schema:identifier	xsd:string
skill	field teacher is skilled in	1			t:Skill

Student

Inherits all fields from Person and adds extra property "age" an extra tab with the extra properties must exist

Name	Description	Min	Max	sameAs	datatype
id	unique record identifier	1	1	schema:identifier	xsd:string
age	age of student	1	1		xsd:integer

[
  {"id":  "s1", "first_name":  "Jane", "last_name":  "Smith", "age":  22},
  {"id":  "s1", "first_name":  "Gino", "last_name":  "Santi", "age":  25}
]

Course

Name	Description	Min	Max	sameAs	datatype
id	unique record identifier	1	1	schema:identifier	xsd:string
name	name of a course	1	1		xsd:string

Schedule

Name	Description	Min	Max	sameAs	datatype
id	unique record identifier	1	1	schema:identifier	xsd:string
teacher	schedule belongs to	1	1		t:Teacher
course	course within schedule		1		t:Course
start_date		1	1		xsd:date
end_date		1	1		xsd:date

Example data

When no id is supplied records will be created and an id will be assigned This example will create a schedule, teacher and course record. The skill and student records are referenced by id and must exist.

{
  "type": "schedules",
  "attributes": {
    "teacher": {
      "first_name": "John",
      "last_mame": "Doe",
      "skill": [{"id":  "1"}, {"id":  "2"}]
    },
    "students": [{"id": "s1"}, {"id": "s2"}],
    "course": {
      "name": "Something 101"
    },
    "start_date": "2021-10-01",
    "end_date": "2022-01-01"
  }
}

Create schedule with existing teacher and course records

{
  "type": "schedules",
  "attributes": {
    "teacher": {
      "id": "1"
    },
    "course": {
      "id": "A23B-101"
    },
    "start_date": "2021-10-01",
    "end_date": "2022-01-01"
  }
}

Solis API

Solis::ConfigFile

Static class to read and manipulate config.yml file

name=: name of config file defaults to config.yml
path=: location of config file defaults to ./config.yml or ./config/config.yml
[key]=: lookup or set a key in your config file
include?(key): is key available in config file

Solis::ConfigFile.path='/path/to/config/file'
raise ':key not found' unless Solis::ConfigFile.include?(:key)

key = Solis::Configfile[:key]

Solis::LOGGER

Logger class defaults to STDOUT for now

TODO: check if this needs to be configurable

Solis::VERSION

Returns Solis version number

Solis::Error

List of Solis errors

Solis::Error::GeneralError

An unknown error

Solis::Error::InvalidAttributeError

Attribute error. Happens when data does not match model

Solis::Error::NotFoundError

When query returns not found

Solis::Graph

Solis::Model

Solis::Resource

Solis::Query

Solis::Shape

Solis::Shape::Reader

Solis::Shape::Reader::File

Solis::Shape::Reader::Sheet

Setup Solis

Solis::ConfigFile.path = './'
solis = Solis::Graph.new(Solis::Shape::Reader::File.read(Solis::ConfigFile[:solis][:shacl]), Solis::ConfigFile[:solis][:env])

TODO:

extract sparql layer into its own gem

Installation

Add this line to your application's Gemfile:

gem 'solis'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install solis

Usage

Transforming a Google Sheet into a SHACL file and Entity model.

Google sheet template example

Tabs starting with an underscore define general metadata - _PREFIXES: ontologies to include in SHACL file - _METADATA: key/value pairs describing the ontology - _ENTITIES: a list of entities describing if it is a sub class of or same as an external entity

Every entity that is referenced in _ENTITIES can be further described in its own tab.

TODO: Write usage instructions here

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/solis. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Solis project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

mehmetc/solis