clarify timestamps in utc and hide properties from schema #788
Conversation
| # Takes a tab delimited text file containing the list of feature buckets | ||
| # as copied from Google Sheets and convert into an MD list | ||
| # | ||
| #a |
|
|
||
| ROOT_DIR=$(realpath $(dirname $0)/..) | ||
| cd $ROOT_DIR | ||
|
|
||
| OP= |
There was a problem hiding this comment.
OP? Pretty cryptic... OPTION?
| @@ -68,6 +39,19 @@ find $TMP_DIR -type f -exec sed -i 's/file://' {} \; | |||
| # is one level down | |||
| find $TMP_DIR -type f -exec sed -i 's;(../docs/;(../../docs/;' {} \; | |||
|
|
|||
| # Hide properties according to the hide me list | |||
There was a problem hiding this comment.
redundant comment (given the echo line right after it)
| @@ -0,0 +1,29 @@ | |||
| # Properties to hide from human readable schema documentation | |||
There was a problem hiding this comment.
The main problem I see here is that somebody is going to go look at the JSON specification anyway, which will then be inconsistent with the generated documentation. I'm not sure there's any great solution here, but just something to keep in mind.
The real problem is that people shouldn't be coding to the schema since it's a very incomplete specification compared to what the behavior aspects of the system are.
Nit: The other way to handle this would be to have something in the schema itself (e.g. "$when") that indicates when it's required/allowed -- so at least all the code/specification is in one place, rather than spread across different files. I.e. consider having this information pulled from the schema itself, not from this file.
| @@ -7,7 +7,7 @@ | |||
| "additionalProperties": false, | |||
| "properties": { | |||
| "timestamp": { | |||
| "description": "RFC 3339 Timestamp the state payload was generated", | |||
| "description": "Not published by devices which publish , appended to message subblocks within cloud pipeline. RFC 3339 Timestamp the payload was generated", | |||
No description provided.