Project

solis

0.0
The project is in a healthy, maintained state
The SUN in latin or is it SILOS spelled backwards. Turn any SHACL file or Google sheet into an API, ORM, documentation on top of a data store
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 5.19
~> 13.0

Runtime

~> 1.7
~> 1.1
~> 5.2
~> 0.13.0
~> 2.2.0
~> 2.7
~> 1.6
~> 5.1
 Project Readme

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

Template model

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.