---
# System prepended metadata

title: SOyA Visual Editor
tags: [soya]

---

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>&nbsp;&nbsp;soya_yaml: "YAML"} |
| &nbsp;&nbsp;->&nbsp;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 |
| &nbsp;&nbsp;->&nbsp;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