name changes to types/format #12

mixmix · 2021-08-11T22:43:26Z

⚠️ assumes #11 is merged

context

on an @arj03 @mixmix @keks call discussing proposed changes with POBox, we got stuck into asking "what is a type, what is a format".
I think we arrived at an idea like:

a "type" is like a domain, a grouping based on similar functions that you would want to perform
a "format" is a associated with a specific "recipe" in that type/domain
- this recipe includes algorithm AND context (e.g. this is a signature of a bendy but content field)
- it's not useful / safe enough to just say "ed25519"

we also realised that some type/formats are locked in by use, but the naming of it is still flexible. This means that e.g. type 3, format 0, which was "diffie-hellman, ed25519" is being proposed to rename to "key, box2-dh".
This reflects the realisation that "diffie-hellman" is waaaay too vague and what we actually want to be able to talk about are encryption keys, and which exact recipes (format) they were used in

naming of fields

so naming is going to change some because we've realised some of the types/ formats were not tight enough.

I am also interested in changing names so that we can easily use names programatically when importing bfe.json.

Use cases:

we're using bfe.json in ssb-bfe and we have functions which depend on the type/format string names
I want to write functions which use this bfe.json definition to generate SSB-URIs for some types.

proposals

we use the same name in README.md as in bfe.json
- e.g. if type 0 = msg we use msg in the docs
we don't use names with / or \s in them
- this makes creating and parsing a URI harder
we choose relatively short names
- prettier, shorter URIs
- if this is a challenge we could split out e.g. type.type into `type.textHandle" and "type.description"
  - if we do this, we could relax (1)

This PR executes these proposals to show more explicitly what I mean

README.md

arj03 · 2021-08-12T06:39:40Z

Some suggestions that would be good to take into consideration before merging this.

staltz · 2021-08-12T07:12:30Z

README.md

+ |:-----------:| ------------------ |
+ | 0           | feed               |
+ | 1           | msg                |
+ | 2           | blob               |


Would be nice to preserve what was before, i.e. uppercase. Otherwise it feels like it's undoing what I did here 11f7d16

I was following the principle of keeping the string the new ad the steering names in the bfe.json
So that people using NAMED_TYPES can just look at this table and type it without having to guess the case, spaces, hyphens

So that people using NAMED_TYPES can just look at this table and type it without having to guess the case, spaces, hyphens

There is bfe.json for that.

Yeah I'm i at what you mean. I think i was being paranoid expecting people to get confused. But if you think it's fine I'm happy for readme to be more human descriptive

Oh, you know what? We could have a third column that reflects the name used in bfe.json

README.md

staltz · 2021-08-12T07:16:21Z

README.md

-|-----------|-------------|-------------|-------------|-----------------|
-| 5         | 0           | Arbitrary   | box         | [private box]   |
+|:---------:|:-----------:|-------------|-------------|-----------------|
+| 5         | 0           | Arbitrary   | box1        | [private box]   |


This one still confuses me, which one is it, box1 or box? I honestly don't know. I know that once code broke everywhere because we were using box1 and it had to be box. But I think (??) ssb-tribes uses box1.

Ssb tribes uses box2
The original is box, but since the advent of box2 we talked about box saying "box1"... but the suffix is the OG box

At least I think that's how it went down

staltz · 2021-08-12T07:16:43Z

README.md

-| 6         | 2           | 0 bytes     | Nil         | [null pointer]                |
-| 6         | 3           | Arbitrary   | Arbitrary bytes | N/A |
+|:---------:|:-----------:|-------------|-------------|-------------------------------|
+| 6         | 0           | Arbitrary   | string-UTF8 | [UTF8]                        |


Would appreciate if this is reverted.

Please respond to my values /proposals
Specifically, I don't want spaces in the name because it makes uris have to have some rule for dealing with them (or you could propose one)

The response to values/proposals is that this markdown document is for humans to read, so let's use formal English, while the json is for computers to parse. In the markdown we should be trying to explain to people what this is, and this table doesn't look like it's explaining, looks like it's stating raw data.

As for URIs, we're not going to have SSB URIs for these Generic data formats, so I don't understand what's the need for the hyphen.

Agree about ssb uri for generic types. I reckon that can be reverted happily then

bfe.json

staltz · 2021-08-12T07:18:30Z

bfe.json

    ]
  },
  {
    "code": 3,
-    "type": "diffie-hellman",
+    "type": "key",


Maybe "encryption key" (was that what we agreed on in the meeting? I don't accurately remember)? "key" is a very generic word.

Correct but in the types key is only ever going to mean a key for unlocking.

See also "no spaces / short words for ssb uri"

This PR then automatically means you're proposing the SSB URI ssb:keys/box2-dm-dh/ and I believe ssb:keys/ is going to confuse a lot of people on what it means (given the existence of ssb-keys). Why not ssb:encryption-keys/box2-dm-dh ?

Mainly because it's hella long, and I wasn't to save my bytes!

I'm up for something different to reduce confusion. Couldn't think of anything right though. Maybe emoji? Joking

It's not prohibitively long. Remember SSB URIs are for human readability (while still computer parse-able), and we have other long SSB URIs such as ssb:experimental?action=claim-http-invite&.....

staltz · 2021-08-12T07:22:29Z

1. we use the same name in `README.md` as in `bfe.json`

I think most of my inline reviews are related to this. I don't like the idea of using same terms in README and bfe.json. The former is clearly documentation meant for humans to read (what if people don't know that "msg" refers to "message"?) while the latter is a programmatic helper, meant for computers to parse. Different purposes. Otherwise soon we're at the point where ssb-bfe would import literally README.md and parse it.

mixmix · 2021-08-12T12:46:19Z

With this PR I would like us all to own it
I started this because it was an Action from the meeting

I took what I remembered, and integrated what I think will be good, making in mind plans to build ssb uris with this code. Keen to figure out if that's what we all want, and if so how best to do it. This is just a starting point I threw down

README.md

add identity type, with po-box format

add pobox diffie-hellman key type

Co-authored-by: André Staltz <andre@staltz.com>

staltz · 2021-08-13T08:19:58Z

Hold on, I'll make a small PR targeting this name_changes branch.

mixmix · 2021-08-13T20:32:22Z

This is now turning into a mega branch. What do we want to do before merging?
(I feel like I merged the small PRs in the wrong order)

new column in readme.md tables, for bfe.json parity

mixmix · 2021-08-15T23:00:52Z

@staltz I've made that change from key > encryption-key, and merge squashed this.

Thanks for the collaboration on this. I noticed that this is a kinda unique thing in SSB - it's very rare that we force ourselves to commit to a shared specification (though I wish we did this more in some cases!)

arj03 reviewed Aug 12, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

arj03 reviewed Aug 12, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

staltz reviewed Aug 12, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

staltz reviewed Aug 12, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

staltz reviewed Aug 12, 2021

View reviewed changes

bfe.json Outdated Show resolved Hide resolved

staltz reviewed Aug 12, 2021

View reviewed changes

Base automatically changed from add_json to master August 12, 2021 22:38

mixmix added 2 commits August 13, 2021 10:39

name changes to types/format

39d3bac

review changes (to be squashed)

f7cd8bd

mixmix force-pushed the name_changes branch from 4ebfcf1 to f7cd8bd Compare August 12, 2021 22:57

mixmix added 2 commits August 13, 2021 11:01

add pobox diffie-hellman key type

2304c30

add identity type, with po-box format

aaa12ab

arj03 approved these changes Aug 13, 2021

View reviewed changes

staltz reviewed Aug 13, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

mixmix and others added 3 commits August 13, 2021 20:12

Merge pull request #15 from ssb-ngi-pointer/identity

3636fe2

add identity type, with po-box format

Merge pull request #14 from ssb-ngi-pointer/po-box-key

883b59c

add pobox diffie-hellman key type

Update README.md

bbb9448

Co-authored-by: André Staltz <andre@staltz.com>

new column in readme.md tables, for bfe.json parity

576e5ef

staltz and others added 2 commits August 14, 2021 09:13

Merge pull request #18 from ssb-ngi-pointer/third-col

65a7633

new column in readme.md tables, for bfe.json parity

rename key > encryption key

e09bb27

mixmix merged commit 29e3330 into master Aug 15, 2021

mixmix deleted the name_changes branch August 15, 2021 22:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

name changes to types/format #12

name changes to types/format #12

mixmix commented Aug 11, 2021

arj03 commented Aug 12, 2021

staltz Aug 12, 2021

mixmix Aug 12, 2021

staltz Aug 13, 2021

mixmix Aug 13, 2021

staltz Aug 13, 2021

staltz Aug 12, 2021

mixmix Aug 12, 2021

staltz Aug 12, 2021

mixmix Aug 12, 2021

staltz Aug 13, 2021 •

edited

Loading

mixmix Aug 13, 2021

staltz Aug 12, 2021

mixmix Aug 12, 2021

staltz Aug 13, 2021

mixmix Aug 13, 2021

staltz Aug 13, 2021

staltz commented Aug 12, 2021

mixmix commented Aug 12, 2021 •

edited

Loading

staltz commented Aug 13, 2021

mixmix commented Aug 13, 2021

mixmix commented Aug 15, 2021

name changes to types/format #12

name changes to types/format #12

Conversation

mixmix commented Aug 11, 2021

context

naming of fields

arj03 commented Aug 12, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

staltz Aug 13, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

staltz commented Aug 12, 2021

mixmix commented Aug 12, 2021 • edited Loading

staltz commented Aug 13, 2021

mixmix commented Aug 13, 2021

mixmix commented Aug 15, 2021

staltz Aug 13, 2021 •

edited

Loading

mixmix commented Aug 12, 2021 •

edited

Loading