Be more explicit documenting Dr. Syntax's objects #9
Conversation
Adds examples and scannable lists of keys used in objects and whether they are required or optional, to make it easier to review without having to check against existing recipe files. Also clarifies that: * storing files in JSON is convention not requirement, except in the case of nosebag itself * other keys are permitted, but you use them at your own risk against future additions to Dr. Syntax
| @@ -91,7 +186,5 @@ Ingredients and groups are serialised as one JSON object, stored as | |||
| tools to suggest ways of scheduling the steps of multiple recipes you need | |||
| to cook at once, such as for a dinner. | |||
|
|
|||
| * group and ingredient names are singular and lower-cased. | |||
There was a problem hiding this comment.
I suggest we keep this advice for ingredient names, noting that while they may not appear in the ontology, they should still follow the convention that the ontology itself uses.
| @@ -9,64 +9,159 @@ Dr. Syntax (in America known as Syntax, M.D.) | |||
| is an object model, and file layout | |||
| for representing recipes, ingredients, and shopping lists. | |||
|
|
|||
| Examples are shown in JSON format, and the `nosebag` project will continue to | |||
| use JSON, but Dr. Syntax is format agnostic as long as the object can be | |||
| serialised and deserialised intact. | |||
There was a problem hiding this comment.
I might add something like:
Where necessary, the serialisations can be referred to as "Syntax JSON" or "syntax.json", "Syntax TOML" or "syntax.toml", and so on.
| Examples are shown in JSON format, and the `nosebag` project will continue to | ||
| use JSON, but Dr. Syntax is format agnostic as long as the object can be | ||
| serialised and deserialised intact. | ||
|
|
||
| ## Object model | ||
|
|
There was a problem hiding this comment.
I think we need something at the top of this section which talks about ontology + recipe list + recipes before it gets into the details.
| ### The list of known ingredients — `ontology.json` | ||
|
|
||
| Stored serialised as `ontology.json`, the ontology is an object containing | ||
| an abstraction of foodstuff used in recipes. |
There was a problem hiding this comment.
"an object listing the foodstuffs used in recipes"? Yes, it's an abstraction, but I'm not sure saying that makes things clearer.
|
|
||
| ### Groups | ||
| Stored serialised as `recipes.json`, the list of recipes is an array of | ||
| strings that represent the directory relative to the location storing both |
There was a problem hiding this comment.
Since nosebag can work over HTTP, it's not necessarily the directory. Perhaps just a note that "equivalent things happen" under HTTP? Or "path"?
| ``` | ||
|
|
||
|
|
||
| ### A recipe — `<dir>/recipe.json` | ||
|
|
||
| The recipe core object is serialised as JSON, and stored as `recipe.json` |
There was a problem hiding this comment.
If it's no longer the case that Dr. Syntax is always JSON, this should be updated.
| necessary (eg "more if they are small") | ||
|
|
||
| If both `unit` and `notes` are not needed, the object can be collapsed to a | ||
| positive integer (eg requiring 2 onions has no new unit to be expressed). |
There was a problem hiding this comment.
Not sure what the word "new" is doing here?
Closes issue #2
Adds examples and scannable lists of keys used in objects and whether
they are required or optional, to make it easier to review without
having to check against existing recipe files.
Also clarifies that:
case of nosebag itself
against future additions to Dr. Syntax