progress tracking and documentation for SOyA Visual Editor -- public!
# SOyA Visual Editor
#### Links
* Visual Editor: https://soyabud.ownyourdata.unterholzer.dev/
* Github Repo: https://github.com/OwnYourData/soya
* SOyA Documentation: https://ownyourdata.github.io/soya/
* [old GDoc](https://docs.google.com/document/d/16rR-_wyEve2mVQMod6WQ71hKp1Ik7X1uxpgdyvxAG1g/edit#heading=h.pg67v59wmbqx)
* Test Instance: https://soya2.data-container.net
#### Tasks
- [x] Christoph: infrastructure setup (HackMD, Github, deployment)
- [x] Gabriel: initial demo with [DataBud](https://github.com/OwnYourData/semcon/tree/main/databud) branch
- [x] Christoph: describe user journey for working with tags
#### Bugs
- [x] Update in SOyA structure requires page refresh
steps to reproduce:
1) edit 'Person', e.g., rename `age` to `age1`
2) a new DRI record is correctly installed but selecting 'Person' again still shows attribute name `age`
3) click "Refresh" in Browser and select 'Person' -> `age1` is displayed correctly
- [x] Meta section does not show data from `meta`
## Meeting 2024-10-03
Updates Gabriel:
- [x] Why is `zQmcfjy3dqNXS96B33hYjjdoyiH7PCTBWPVAQjMgLpGqWTK`shown twice in the left panel? (Bug?)
`GET /api/soya/query` returns it only once
- [x] hide "Default" in left panel (I know, we initially talked about leaving it but since taxonomy handling is clarified it is not necessary anymore)
- [x] Button "New":
- `System` and `Meta` empty (and cannot be edited)
- empty `Content` editor (editable)
- Button "Save" uses either "push" (if json-ld is selected) or "init-push" (for yaml)
- [ ] tab "Form" next to "Raw Data" with functionality from soya-form
- is it possible to rename "Raw Data" to "SOyA Structure"?
<details><summary>Done</summary>
Updates Gabriel:
- [x] use `id` from data container to reference records
history structure: `{:schema, :name, :tag, :dri, :id, :date, :yaml}`
- [x] show `meta` associated with SOyA records
- query data with `GET /api/data?id={id}` (instead of `GET /{dri}` or `GET /{dri}/yaml`)
- response:
- `"data"` - SOyA structure as JSON-LD
- `"soya_yaml"` - SOyA structure as YAML
- `"meta"` - Metadata for SOyA structure
- [x] save `meta` when updating SOyA records
use the following structure for `POST /api/data`
```json
{
"content": JSON-LD structure,
"soya_yaml": YAML structure (if available),
"meta": meta data
}
```
</details>
## Goals
* enable non-technical people ("Sebastian" persona) to manage SOyA structures: soya init-push, pull, info
* ensure complete documentation
make sure all functions are properly documented
* update SOyA repo code to `oydeu/dc-base`
support for `jsonb` data type, common code base
* nice to have: [tag support](#SOyA-Tags)
## Identified Tasks for Documentation
- [ ] repo deployment
## SOyA Tags
- user Docker tags as model/pattern
- default tag: `current`
- allow to give DRI versions a human-readable name
- soya command: `soya tag Person:current Person:240814`
or `soya tag DRI Person:240814` or `soya tag Person Person:240814`
* creates a permanent record of the SOyA structure `Person` with the tag `240814`
* API endpoint: `POST /api/soya/tag`
body: `{"original": "text", "tag": "text"}`
* implement functions that use soya_name and update to `name`:`tag`
* soya pull
* soya info
* schema: tag wenn vorhanden / current für aktuellen
* tag (neu): soya_tag
* dri: immer soya_dri
- Constraints
- soya_name + tag is unique (re-using a tag overwrites previous tag)
- `current` is the default tag (every soya_name has exactly one `current`)
- Visual Editor
- if there is a tag, show it instead of the DRI
- sorting for a `soya_name`:
- `current` first
- tags in alphabetical order
(nice to have soring: alphabetical part ascending and numbers descending)
## SOyA Repo Endpoints
* old Swagger: https://api-docs.ownyourdata.eu/soya/
* current Doku: https://ownyourdata.github.io/soya/#repository
| Command | Endpoint | Body/Parameters |
| ------- | -------- | -------- |
| soya push<br>soya init-push | ✅ POST /api/data | {content: "JSON-LD", <br> soya_yaml: "YAML"} |
| -> incl. | ✅ GET /api/data/:dri
| soya pull | ✅ GET /{soya-name} | - |
| soya pull --type=yaml | ✅ GET /{soya-name}/yaml | - |
| soya info | ✅ GET /{soya-name}/info | - |
| soya similar | ✅ POST /api/soya/similar | {JSON-LD} |
| soya query | ✅ GET /api/soya/query | ?name=text |
| -> incl. | ✅ POST /api/soya/info | {_json: ["soya_dri"]}
<details><summary>Data Structure in <code>oydeu/dc-base</code></summary>
The following fields are used in the model `Store` within a SOyA repository:
* `id`: counter (auto increment) from database (unique)
* `dri`: content based address of the record (hash value from `item` and `meta`) (unique)
* `item`: JSON-LD representation of the SOyA structure
* `meta`: always includes the content based address `soya_dri`
* `soya_yaml`: YAML representation of the SOyA structure (optional)
* `soya_name`: name of the SOyA structure (human-readable)
* `soya_dri`: either content based address or name of SOyA structure
</details>
<details><summary>SOyA DRI Calculation</summary>
1. transform JSON into canonical form according to [RFC8785](https://datatracker.ietf.org/doc/html/rfc8785)
2. remove self-referencing entries required by JSON-LD (`@base` in `@context`)
3. calculate the hash value using [Multihash](https://github.com/multiformats/multihash) (`SHA2-256`) and
encode the resulting binary with [Multibase](https://github.com/multiformats/multibase) (`base58btc`)
</details>
<details><summary>soya push</summary>
*Description:* write a SOyA structure to the repository
```bash=
cat soya.jsonld | soya push
````
*Variants and Options:*
* `soya init-push`: performs soya init first and then writes YAML and JSON-LD to repository
* `--repo` URL of non-default repository
* default repository: https://soya.ownyourdata.eu
* [ ] https is default protocol and can be ommitted (e.g. soya push --repo soya.example.com)
**with `curl`**
```bash=
# write data
cat example.jsonld | curl -d @- \
-H "Content-Type: application/json" \
-X POST https://soya.ownyourdata.eu/api/data
# retrieve name from element that was written
curl "https://soya.ownyourdata.eu/api/data/1?p=id&f=full"
```
</details>
## Parking Lot for Ideas
### Authorization
- requires stable authorization of oydeu/dc-base
- configuration options for SOyA repo
- open: everybody can do everything:
soya-playground.ownyourdata.eu
- restricted: author can do everything, others can read
soya.ownyourdata.eu
- closed: non-public instance, only author has write access to SOyA structure, everyone needs credentials for access
soya-repo.corporation.com
- "authorship" for SOyA structure
- allows to delete SOyA structure
Sign in with Wallet
Connect another wallet