For what its worth I’m running Xandikos as a local CalDAV server and I have had no problems with it. That talks to Etar on the phone, Thunderbird on the desktops/laptops, and Ive found it pretty easy to write utility programs to run against it too. The backend is files version-controlled with git.
this reminds me we had plans to do this kind of thIng. maybe as a winter project.
I have ported my prime number generation algorithm (basically a sieve of Eratosthenes with some optimisations) to Typst.
I very much hope that this is never useful to anyone, including me. But it was great fun to write.
I wish I was coding anything.
Instead my primary tools these days are Confluence, Draw.io, Word and Powerpoint
I am building tools that use JSON files (created by the user, or if I’m lucky and someone else writes the code maybe some future software) as their input. Is there a standard format for documenting which fields are needed and what should go in them? (This is less “must be a string” and more “if it’s a string that appears in this place in this other file, that hash will be added to this hash before it’s used”.)
json.schema is a thing. JSON Schema - JSON Schema examples
openapi (formerly known as swagger) is also a thing that documents interfaces for mostly REST services that mostly use json. sample openapi.yml · GitHub
Afaik json.schema is far more fluid than xsd (xml schema) is at this point. it is not as well-defined (yet)
But that’s the approaches I would try to document my format in and both should include the optional descriptions. Since you are not (yet) defining an automated interface via f.e. a REST service you would only be using the openapi subset that defines the data to be sent but that’s totally possible. You could later integrate that easily via type references if you felt like going down the service route.
Strangely, I am working on a similar thing at work. A portable JSON file that users (engineers, but still non-programmer users) create as an input and output of some automation scripts.
I have decided to forgo schema standardization until I’m done, but I am not looking forward to creating the schema.
I’ve used Swagger/OpenAPI before and I can confirm it’s quite handy
I hate any format that uses correct indentations as part of its definition however…
yaml despite that particular short-coming is human readable in ways that most schema files are not.
and the indentation issue is handled by the professional
on the other hand if the users have to write the data by hand a json schema is probably more aligned with the desired output than the yaml is and so the translation from schema to user-input is easier.
Well, if the plan goes off accordingly, the initial JSON data will be created by a script itself that prompts user for inputs and spits out the JSON file; a user would be able to edit the file to account for one-off situations.
Working on this, I realized why YAML exists when JSON is, in my opinion, the superior format: editing JSON by hand, there’s way too many "
s.
also json has no way to include comments in a json file which I find is an big flaw.
Sure it does!
{
"some object": {
"comment": "This is a comment!",
"something_important": true
}
}
Nope. It works differently:
{
"some object": {
"description_of_something_important": "This is a comment!",
"something_important": true
}
}
edit: or with a German domain for the software “desc_of_etwas_wichtiges”
editedit: also the amount of misplaced braces in any human edited json file is almost as bad as having one wrong space breaking your yaml
My “this wasn’t as easy to find out as I expected” piece of YAML knowledge, in case it’s helpful to anyone…
Blank lines in block literals
In a block literal scalar value (i.e. indented multi-line content introduced with the |
character), an “empty line” is well-defined as a line which has the indentation prefix but nothing more, but it is not obvious from the spec how “blank lines” (just a newline – no indentation) will/should be treated within that block scalar value.
I wanted to know this because I was seeing such cases in some existing files, and I couldn’t tell if it was valid or “accidentally working”. I thought this would be easy to find out, but I ended up asking one of the spec authors, and the response was:
Within literal scalars, any empty lines or lines with fewer spaces than the block indentation level (including blank lines) are loaded as newlines in the result. IOW you don’t need to match the indentation level with spaces on a blank line. If you use more than the needed indentation level, those extra spaces are content in the result.
https://play.yaml.io/ confirms this in practice.
As using completely blank lines avoids both potential indentation mishaps when editing, and also potential issues with text editors treating the indentation as unwanted trailing whitespace, it’s a sensible standard approach.
While I understand this and appreciate the human-editability it provides, having to render whitespace in my editor to edit a file is such a nightmare.
Perhaps, though, no more than pressing "
every 0.4 seconds while using JSON
I enjoy writing YAML more than I enjoy writing JSON. (Especially since a lot of the libraries I use still don’t support trailing commas.)
But YAML has the Norway problem, and huge security holes with its object loading capabilitty.
I’d define a sort of “Sane YAML” without those dodgy bits, but it ends up looking a lot like JSON.
Previous place I worked used a JSON-but-allows-comments format for some of their files. It’s easy enough to use a wrapper to strip them out before parsing the JSON-proper, and they were auto-generated files so the comments were consistently formatted. Obviously only works when the files are never going to be parsed as true JSON.
Too many fjords?
I asked Google if YAML had a Norway problem, and it said, NO
No, this is a real thing. You list, say, country codes:
- fi
- se
- no
- dk
and it doesn’t work. Norway is missing. (Edit: I’ve told the syntax highlighter on the forum to use YAML mode, which makes it obvious.)
Because “no” is a synonym for boolean false. If you want it to work, you have to put it in quotes. And at that point, you might as well write JSON anyway.
No way!