Hi Alex,
HTTP Adaptations draft raised a concern that the only way to document
a new OCP parameter is to describe it using low-level syntax BNF.
Using BNFs for declarations is bad because it covers/hides the
important information in syntax sugar and makes the reader think that
a parameter may have some syntax features not already documented in
the OCP Core. Moreover, if extension authors are not very careful,
they could accidently introduce new syntax features which is a bad
idea (unless explicitly negotiated first). Finally, since all BNFs
look similar, using BNF makes OCP parameters look like HTTP headers
(that have to be defined using BNF because there is nothing else
available for HTTP) and vice versa, which is not that good since HTTP
syntax is actually different from OCP syntax.
If there are no objections, I am going to add a section to OCP that
will describe a very simple/basic way to document any parameter
without using a syntax BNF. The same interface will be used in OCP
Core, of course. Here is a sketch/template of possible choices
<name> : atom;
<name> : list< <item> >;
<name> : structure {
<member> [<member>]; // anonymous
<member-name>: <member>; // required named
[<member-name>: <member>]; // optional
};
This is similar to C/C++ typedefs but uses more-intuitive Pascal-like
declaration syntax (new type name first, followed by the definition).
The declaration would be accompanied by semantic rules, of course.
Note that we already use something like the above for OCP messages
(defining an entire message using BNF would be tedious).
Here are a few usage examples from OCP Core:
Uri: atom;
Service: structure {
Uri;
};
Services: list<Service>;
And from the HTTP draft:
Am-Part: atom;
Am-Parts: list<Am-Part>;
Http-Profile: structure {
Uri;
[Aux-Parts: Am-Parts];
[Skip-Parts: Am-Parts];
};
And here is how NO message can be declared using the above
declarations and current message declaration syntax:
name:
NO
anonymous parameters:
Services
named parameters:
[sg-id: Uni]
payload:
undefined
Any objections or better ideas?
Please add this to the core. I agree that such way of documentation will help.
Could you even improve the Service declaration a little?
Some way that allows to show that there are optional named parameters (none
defined by core).
So, that it will allow the HTTP draft to define that
Http-Profile: Service
and that Aux-Parts is a named parameter of that structure.
Your proposed solution has the disadvantage that NO has Services parameter,
defined as a list of Service and in HTTP there is no mapping from HTTP-Profile
to Service and no hint that NO anonymous parameter is being changed from
Services to Http-Profiles.
Regards
Martin