List structure

[Dracon23]

(continued from my Gist

This is a semi-initial draft of what we should include into the list entries and how they should be structured.

Draft Version - r3-22052709
Last modified - 22-05-27

<?xml version="1.0"?>
<ReadingList xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Name>Example Reading list</Name>
    <Books>
        <Book Series="Awesome Name" Number="24" Volume="261" Year="2200">
            <Series>
                <Name>Awesome Name</Name>
                <Volume>261</Volume>
                <StartYear>2200</StartYear>
                <Identifiers>
                    <ComicVine>8186351684165</ComicVine>
                    <Alternative>864553648</Alternative>
                </Identifiers>
            </Series>
            <Issue>
                <Identifiers>
                    <ComicVine>87374928374982374982</ComicVine>
                    <Alternative>56415163156151</Alternative>
                </Identifiers>
                <Number>24</Number>
            </Issue>
            <Event>
                <Identifiers>
                    <ComicVine>1248237528354</ComicVine>
                    <Alternative>21846084151</Alternative>
                </Identifiers>
                <EventName>Superreal Event</EventName>
                <Position>1</Position>
            </Event>
            <Characters>
                <Character>
                    <Identifiers>
                        <ComicVine>123741234</ComicVine>
                        <Alternative>12381724</Alternative>
                    </Identifiers>
                    <Name>Deadpool</Name>
                </Character>
            </Characters>
        </Book>
        <Book Series="Awesome Name" Number="25" Volume="261" Year="2200">
            <Series>
                <Name>Awesome Name</Name>
                <Volume>261</Volume>
                <StartYear>2200</StartYear>
                <Identifiers>
                    <ComicVine>8186351684165</ComicVine>
                    <Alternative>864553648</Alternative>
                </Identifiers>
            </Series>
            <Issue>
                <Identifiers>
                    <ComicVine>8737492837498237530</ComicVine>
                    <Alternative>56415163156591</Alternative>
                </Identifiers>
                <Number>24</Number>
            </Issue>
            <Event>
                <Identifiers>
                    <ComicVine>1248237528354</ComicVine>
                    <Alternative>21846084151</Alternative>
                </Identifiers>
                <EventName>Superreal Event</EventName>
                <Position>1</Position>
            </Event>
            <Characters>
                <Character>
                    <Identifiers>
                        <ComicVine>123741234</ComicVine>
                        <Alternative>12381724</Alternative>
                    </Identifiers>
                    <Name>Deadpool</Name>
                </Character>
            </Characters>
        </Book>
    </Books>
    <Matchers />
</ReadingList>

[Dracon23]

Looking at splitting lists (i. e. master list), would it make sense to include list details? like part number and a follow up?

[btxgit]

HEre are some ideas that I'm bringing up because you don't want to have to go back and make changes that break the old format :)

I. ComicVine (or other DB) IDs:

Everywhere has these 2 concepts - one for the series, one for the specific issue. Make sure to define specific names for the variables so people know what they're dealing with. So you COULD support any number of these. Or a limited number. Something like:

Even if there's just 1 right now, comicvine could easily go away, or everyone could switch to a different database. It's a good idea to design it so it won't break the first time situations change. On the other hand, allowing any source could make it common to have random sources that will be essentially worthless.

There's as ton of Ids that seem like they'd be useful, but they're almost never given (or have historical issues like EAN13 / UPC / ISBN has had. I can speak in depth about this, as I've tried to work with it before with comics).

II. Volumes - Don't use that word, seriously. Series="Name" start_year="1983" although there's a handful where that doesn't identify it. Better would be something like "start_date" and have support for year-only ("1983"), year-month ("1983-06") season ("Winter, 2021") ... other? Be very specific with the date field - You need to specify which date it refers to (cover date is the traditional value).

Suggestion - if volume and year have different meanings, you should demonstrate that in the draft example.

III. Partial files / updates

• What if you wanted to import CBL files? Is that valid? This may be too much for an early spec
• IMO a must have: What if you have like 750 reading lists, and someone comes along and updates 412 of them? You want - at the least - a way to determine whether the server version is newer than your copy. So maybe ... unix epoch to a fraction of a second (like python's time.time() or php's gettimeofday(true))
• POTENTIALLY VERY COMPLICATED - makes sense for a v2.0 feature): accepting updates from multiple sources. Consider this one carefully!! IMO the way to go is to have editors who can edit any document. Every edit should be recorded.

IV. Naming of the lists - assign persistent names (like a guaranteed "as long as this list exists, it will be named _____" ? Or are you going to use values that only have meaning to the server? That's a valid answer, but it's worth considering. Why? Consider someone makes a complete arc download for a major cross-series crisis. You want to be able to import the list and have it work like expected.

[jakem742]

II. Volumes - Don't use that word, seriously. Series="Name" start_year="1983" although there's a handful where that doesn't identify it. Better would be something like "start_date" and have support for year-only ("1983"), year-month ("1983-06") season ("Winter, 2021") ... other? Be very specific with the date field - You need to specify which date it refers to (cover date is the traditional value).

While I agree with you that the field names are terrible, I think we have to keep all the field names the same as they are currently. Either that or we completely change the file format and come up with a new name because we'd be breaking compatibility with every system which uses the CBL format. We can add new tags, but I don't think it's a good idea to modify anything currently in the system.

III. Partial files / updates

See my reply below for ideas on handling this. I think it's actually pretty feasible to use a single master-list to generate any "partial" lists. This way people would simply update the master-list and regen any partial lists they're after using a script we provide. This seems quite practical and efficient imo. If people have a tonne of these partial lists, we could easily make a way to save a list of files to generate so it's simply a matter of the end-user downloading updates and re-running the script. Should be fast and simple.

[Dracon23]

Going to reply to various things in no specific order while updating the draft.

Suggestion - if volume and year have different meanings, you should demonstrate that in the draft example.

This was a bad choice of example value on my end, fixed in the update.

start_year="1983" although there's a handful where that doesn't identify it. Better would be something like "start_date" and have support for year-only ("1983"), year-month ("1983-06") season ("Winter, 2021") ... other? Be very specific with the date field - You need to specify which date it refers to (cover date is the traditional value).

While we're trying to "extend" the lists with important information as much as possible, in the end we do not want to break BC here (Correct me if I am wrong, then I won't mind and break stuff!) and HAVE to keep those fields there...

I. ComicVine (or other DB) IDs: [...] comicvine could easily go away[...]

Was having this in mind for the exact same reason and will include an example how alternatives could look. Also, I would like to hear about other existing identifiers (since you said on Discord, EAN13 had "issues")

[jakem742]

Accidentally deleted my comment before I relocated it to a new reply. :(

Summary of it below:

1. Events - I like the idea, but maybe we structure it more like the Books structure. ie. <Event "details_here" /><Event "details_here" /> .
2. Characters/Teams - Could extend the model to also include key characters/teams within the book?

Name, position and eventID are all handy fields to include for Events, Characters and Teams imo. Although you could possibly forgo the numbers and simply use the position in the main list to order all the sub-lists. This would be cleaner, but also a bit harder for the user to read and tweak.

If we included these tags within every book, we could, in theory, generate every specific character/event reading list from ONLY the master-reading-list. I really love the idea of everything being within a single file. The only downside to this is we'd either need a companion script to generate specific lists separately, or work with app developer's to incorporate these extra tags into their CBL import tool. I have created a new discussion specifically for this here: #10.

[Dracon23]

If we included these tags within every book, we could, in theory, generate every specific character/event reading list from ONLY the master-reading-list.

This is the idea behind my usage of the event tag, and the more identifying info we have in the CBL itself, the better we can generate seperate lists by partial information.