design: multi document file support

[TobiasKadelka]

YAML allows to have multiple documents in one file, devided by ---.

related to:

• 722

• 720

• 703

These ideas are all about allowing multi files as input for onyo new, onyo set (possibly some other commands).

However, it is unclear to me if we want to allow actual assets to be multi file documents, too.

1. Filename: based on the keys inside a file. a. disallow multiple documents in one file for assets? b. just use the e.g. first document as the asset?
2. Validation: validate all documents in a file?
3. How would/could e.g. onyo set, onyo rm and onyo mv just address the second document in a multi doc?

We can either:

• allow multi doc support just for --keys, --yaml and --template
• or we would need to answer the questions above

As a side note: if we would add multi doc support for normal assets, this might be another step from onyo into the DB direction.

[TobiasKadelka]

Also, I wonder what currently happens if a user just adds a second document with i.e. onyo edit. I don't know if onyo would error, or just ignore it.

[aqw]

Just as FYI (this should be handled automatically by whatever library we're using), there's a document start and end. Summary from Wikipedia:

Multiple documents within a single stream are separated by three hyphens (---). Three periods (...) optionally end a document within a stream.

[TobiasKadelka]

Now that we all agree on multi docs being okay as input, but not as valid assets, I want to argue against it, and provide an alternative possibility ;)

In re 1.+2.:I think the filename should be build out of the information from the first document in the file, but all documents in a file should be validated.

As to 3.: In #23 (especially https://github.com/psyinfra/onyo/issues/23#issuecomment-2456817282) we discuss different syntax ideas like

some.<int> could refer to a specific element (index int) in a list "some".

I wonder if there are any problems with following along those lines for files with multiple assets in them, those allowing this as a usecase. Syntax could look like this:

• onyo set --keys a=b --asset display_apple_1234.3
  • sets a=b just for the third asset in a file
• onyo rm display_apple_1234.3
  • removes the third asset in a file, but leaves the rest untouched
• onyo mv display_apple_1234.3 shelf/
  • move the third asset out of the file, creating in praxis a new asset file in shelf

If there is no desire for this, we can stay with the current thoughts as discussed in the chat. But if we add some multi document file support, I think it is worth exploring how the other possibilities could look like, and doing that now, too.