[GH-ISSUE #1396] [BUG] bootstrap.sh documentation unclear #486

New issue

Open

opened 2026-02-27 08:17:31 +03:00 by kerem · 2 comments

kerem commented

2026-02-27 08:17:31 +03:00

Owner

Originally created by @virtuous-sloth on GitHub (Feb 15, 2026).
Original GitHub issue: https://github.com/lldap/lldap/issues/1396

Describe the bug
The text "Each config file can be as one JSON file with nested JSON top-level values as several JSON files." in lldap/example_configs/bootstrap/bootstrap.md is difficult to parse (I am a native English speaker with some technical experience but not a developer). It might be missing words?

To Reproduce
Steps to reproduce the behavior:

Ask a new user of the software to read the bootstrap.md document
Ask them to describe what that sentence means
They might have some misunderstanding

Expected behavior
The new user gains a clear understanding of how many files of what names with what contents can be placed in the bootstrap directories, including any structure options (one files per directory, many files per directory).

Logs
N/A

Additional context
I think this is trying to tell me I can have, in each directory, one single file with some sort of JSON list of user/group-configs/schemas, possibly with or without some enclosing JSON syntax, or I can have multiple files each with a single equivalent individual JSON user/group-config/schema, possibly without or with some enclosing JSON syntax. Perhaps multiple examples contrasting the options would help?

Originally created by @virtuous-sloth on GitHub (Feb 15, 2026). Original GitHub issue: https://github.com/lldap/lldap/issues/1396 **Describe the bug** The text "Each config file can be as one JSON file with nested JSON top-level values as several JSON files." in lldap/example_configs/bootstrap/bootstrap.md is difficult to parse (I am a native English speaker with some technical experience but not a developer). It might be missing words? **To Reproduce** Steps to reproduce the behavior: 1. Ask a new user of the software to read the bootstrap.md document 2. Ask them to describe what that sentence means 3. They might have some misunderstanding **Expected behavior** The new user gains a clear understanding of how many files of what names with what contents can be placed in the bootstrap directories, including any structure options (one files per directory, many files per directory). **Logs** N/A **Additional context** I think this is trying to tell me I can have, in each directory, one single file with some sort of JSON list of user/group-configs/schemas, possibly with or without some enclosing JSON syntax, or I can have multiple files each with a single equivalent individual JSON user/group-config/schema, possibly without or with some enclosing JSON syntax. Perhaps multiple examples contrasting the options would help?

kerem added the

bug

label

2026-02-27 08:17:31 +03:00

kerem commented

2026-02-27 08:17:31 +03:00

Author

Owner

@virtuous-sloth commented on GitHub (Feb 15, 2026):

I decided to dig deeper myself to see if I'm understanding or misunderstanding in some particular way.

I did check that the two-group example is highlighted properly when fed into jq . which to me implies it is or might be valid JSON but it is not itself an array or an object, so perhaps the problem is my brain doesn't fully know what valid JSON is.

I asked an LLM since at least it could search and point me to some info. The LLM said it was not strictly correct JSON but suggested it could be JSON Lines or Newline-delimited JSON. When I looked those up all the examples would only have a series of valid JSON data structures (objects, arrays, bare values?) with no newlines in them thus separated by newlines. But then this example the group objects are formatted with newlines, so now I question my understanding.

Perhaps there are conventions around JSON that I'm not aware. In any case, I still believe that the sentence is difficult or impossible to parse as English on its own.

@virtuous-sloth commented on GitHub (Feb 15, 2026): I decided to dig deeper myself to see if I'm understanding or misunderstanding in some particular way. I did check that the two-group example is highlighted properly when fed into `jq .` which to me implies it is or might be valid JSON but it is not itself an array or an object, so perhaps the problem is my brain doesn't fully know what valid JSON is. I asked an LLM since at least it could search and point me to some info. The LLM said it was not strictly correct JSON but suggested it could be JSON Lines or Newline-delimited JSON. When I looked those up all the examples would only have a series of valid JSON data structures (objects, arrays, bare values?) with no newlines in them thus separated by newlines. But then this example the group objects are formatted with newlines, so now I question my understanding. Perhaps there are conventions around JSON that I'm not aware. In any case, I still believe that the sentence is difficult or impossible to parse as English on its own.

kerem commented

2026-02-27 08:17:31 +03:00

Author

Owner

@nitnelave commented on GitHub (Feb 15, 2026):

I'm not 100% sure, since I didn't write bootstrap.sh (it's a community contribution), but I believe it is newline-separated JSON. But inside a JSON value, you can also have newlines, it keeps parsing a single value until it's complete (matching braces).

@nitnelave commented on GitHub (Feb 15, 2026): I'm not 100% sure, since I didn't write bootstrap.sh (it's a community contribution), but I believe it is newline-separated JSON. But inside a JSON value, you can also have newlines, it keeps parsing a single value until it's complete (matching braces).

kerem referenced this issue

2026-02-27 09:09:42 +03:00

[PR #489] [MERGED] server: ensure first/last name nullable, make avatar long blob in DB #778