search

braid-org / braid-spec

Working area for Braid extensions to HTTP
https://braid.org
233 stars 16 forks source link

Missing grammars in patch format #7

Closed mitar closed 4 years ago

mitar commented 4 years ago

I think you should formally specify the grammars for what you are defining there. Both for the patch specification and for patch itself. Like:

braid(bytes, sync9(array))

What of this is structure, what are values. Where are spaces allowed? Are there comments? How many elements should be there in the parameters? Can sync9 get additional arguments? What are possible values for the first? bytes? Is this a reserved word? Is there a new registry your spec is introducing of those words? Who will maintain that registry, IANA?

Similarly, you have example:

[3:5] = "hello"

Why are quotes there? Where do they come from? What are quoting rules there?

toomim commented 4 years ago

Yes, this is missing. Thank you.

(And FYI the quotes are because the Media-Type in that example is JSON, and that value being set into JSON is a JSON string.)

mitar commented 4 years ago

(And FYI the quotes are because the Media-Type in that example is JSON, and that value being set into JSON is a JSON string.)

I do not think [3:5] is a valid selector for JSON, no?

toomim commented 4 years ago

I do not think [3:5] is a valid selector for JSON, no?

That is valid for JSON. It presumes the value is an array or string, and selects elements 3-5 in an array or string. If the value is not an array or string, it throws an error.

mitar commented 4 years ago

That is valid for JSON. It presumes the value is an array or string, and selects elements 3-5 in an array or string. If the value is not an array or string, it throws an error.

So if those selectors really depend so much on content type, I think all examples should provide that context. Otherwise this is really hard to understand.

toomim commented 4 years ago

It depends not on the Content-Type, but on the Parser specification.

It sounds like we should add some language saying "The Parser is responsible for defining the format of the left-hand-side and right-hand-side in a braid patch."

mitar commented 4 years ago

Yes, you are right. But I think we then have to standardize few of those standard parsers?

toomim commented 4 years ago

Yes, we need specifications for parsers and mergers.

mitar commented 4 years ago

Opened #14 for clarifying the parsers.