Ensure current version is represented in respec

[ikreymer]

Since we now have many TBs of WACZ 1.1.1 files, we should have a ReSpec document that reflects the current version, and may a separate draft that reflects the proposed changes for 1.2. We should have:

• [ ] Edit the current 'latest' draft to be the 1.1.1 version.
• [ ] Add a 'working draft' for 1.2.0 and list changes from 1.1.1

I think the only proposed change thus far may just be the change to profile field?

[edsu]

The datapackage.json section in v1.2.0 changed the mainPageUrl and mainPageDate from v1.1.1 to:

The `datapackage.json` SHOULD include a `home` object to assist
in initial replay of the web collection. This allows rendering software
to choose what initial page to be displayed after opening a WACZ collection.
If present the `home` object MUST include the following properties:

- `url`: The URL of the collection's home page
- `ts`: An [[RFC3339]] date for when the snapshot of URL was made

I should revert that for 1.1.1 right?

Also 1.2.0 doesn't include any information about datapackage-digest.json like 1.1.1 did. So the new v1.1.1 doc will need to bring that back?

[ikreymer]

The datapackage.json section in v1.2.0 changed

I should revert that for 1.1.1 right?

Yes, this is what's currently used in 1.1.1 WACZ, and py-wacz currently supports mainPageUrl / mainPageDate, so should include that.

Also 1.2.0 doesn't include any information about datapackage-digest.json like 1.1.1 did. So the new v1.1.1 doc will need to bring that back?

Yes, let's at least mention the structure of datapackage-digest.json, as its currently being generated for browsertrix cloud WACZ files. The structure is here: https://github.com/webrecorder/wacz-auth-spec/blob/main/spec.md#datapackage-digestjson-file should at least be added, and can link to the signing spec for more details. I think we should probably keep this for 1.2.0 as well, since it is an integral part of WACZ now

[edsu]

Since some of the changes in the 1.2.0 spec would break backwards compatibility with v1.x how about we remove it for now, and introduce a 2.0.0 at a later date if we want to actually make those (and other) changes?

[ikreymer]

Since some of the changes in the 1.2.0 spec would break backwards compatibility with v1.x how about we remove it for now, and introduce a 2.0.0 at a later date if we want to actually make those (and other) changes?

Hm, i don't think it needs to be removed, just make it clear that this not yet implemented, that it's a 'working draft' vs 'production draft'? I think the goal of the changes we have proposed so far was to implement them in next version of py-wacz, wabac.js. Of course, could maintain backwards compatibility with 1.1.x

[edsu]

Ok, we can keep them. Are we not using semver for the spec's version?

[ikreymer]

Ok, we can keep them. Are we not using semver for the spec's version?

Do we have any changes that are not backwards compatible changes thus far? I think the main proposed main changes for 1.2.0 were to the profile and renaming wacz_version -> version, which are fairly minor changes have no a substantive effect on the format - any tool that now supports WACZ equally check these as well. Could be argued they're fairly backwards compatible as far as the spec is concerned, and could even be a 1.1.2 alone per semver, if we were to just release a new spec with only those changes.

[edsu]

Yes, in v1.2.0 there was the addition of a home see above to replace mainPageUrl and mainPageDate. I guess I'm not understanding semver's application to a specification. If you rename one thing to another that would be a breaking change for clients wouldn't it? I think of patch versions as bug fixes (typos etc), minor versions as additive changes, and major versions as removing or changing existing things?

[ikreymer]

Yes, in v1.2.0 there was the addition of a home see above to replace mainPageUrl and mainPageDate. I guess I'm not understanding semver's application to a specification. If you rename one thing to another that would be a breaking change for clients wouldn't it? I think of patch versions as bug fixes (typos etc), minor versions as additive changes, and major versions as removing or changing existing things?

Ah right! Yes, I see what you mean.. Hm, I think it'd be more confusing to go directly to WACZ 2.0 though, maybe we can be more careful and deliberate about property names starting with 1.2.0 to avoid renaming in the future?

[edsu]

I'm seeing now that OCFL had to extend respec so that it could display as recommendation without being affiliated with a W3C group. I guess we will have to do something similar if we want to keep using it, and distinguish between drafts and final versions.