Prezi editorial notes

[azaroth42]

Editorial changes suggested from read-through:

• 1. Does "digital compound object" need to be expanded to be clearer?
• 1. At least standardize compound vs composite
• 1. "of this specification" -> this specification addresses
• 1. + "references to " the resources needed to present them
• 1.1. Now "structured" digital object. (see above)
• 2. The objectives + "described above"
• 2. "Content resources" ? Or lower case as it's not a class? In 2.2 we have Content?
• 2.1. "each with its own descriptive" ... is this clearly about the Collection? "it" could refer to Manifest.
• 3.1.requiredStatement - that the +publishing organization deems ... ?
• 3.1.provider - here "string that contains a URI", compare to rights where "string must be a URI". Prefer be a, not contain a.
• 3.1.thumbnail - is "external resource" necessary to specify? Just resource? Probably comes from it being previously under external links in 3.3.1
• 3.1.thumbnail - images and video_s_ ?
• 3.thumbnail - In Canvas we use "representation" meaning the view. Ambiguous with web architecture use of representation?
• 3.1.navdate - is "a time-based user interface" now ambiguous that we have temporal content resources? Change to 'date' based?
• 3.1.placeholderCanvas - still refers to "A poster Canvas "
• 3.1.placeholder/accompanying Canvas value definition should define the value of type to be Canvas?
• 3.3.1.logo Similarly logo should define the value of type to be Image? (c.f. supplementary)
• 3.2.id is the bold for embedded and referenced needed?
• 3.2.type Does the table need a title or further reference, other than the second para in the prose?
• 3.2.format -- should the note be called out as a note block, or is plain text sufficient?
• 3.3.1.* -- drop "external" ?
• 3.3.1.service -- typo : "Any resource type may have the service property with at least one item"
• 3.3.1.seeAlso -- "Other IIIF resources, such as a related Manifest, are valid targets for seeAlso. " Is that really true??
• 3.3.2 -- has the wrong label of 3.4.2
• 3.3.2.partOf -- is it clear that this is an external but IIIF resource, rather than within a single manifest document?
• 4. The section no longer talks about URI recommendations, which is now down in protocol. Remove from the intro para.
• 4.2. Also implies that type is not mandatory
• 4.5 missing period after mailto
• 5.* often have summaries of the required and recommended properties, but they're not complete. They should either be removed or cross-checked.

[tomcrane]

Commenting on @azaroth42's comments and also adding some more:

1. Does "digital compound object" need to be expanded to be clearer?
2. At least standardize compound vs composite

I think compound is better than composite, as although they mean pretty much the same thing, there is more of a suggestion that each part is different in composite ("a composite material") than in compound. Hundreds of canvases feel more compound that composite.

Suggestion for reorganising the current first three paras:

Access to digital representations of objects is a fundamental requirement for many research activities, the transmission of cultural knowledge, and for the daily pursuits of every web citizen. Ancient scrolls, paintings, letters, books, newspapers, films, operas, albums, field recordings, and computer generated animations are compound objects: they can have many parts, and complex structures. These resources may also bear the written or spoken word, and this linguistic content is often as important as the visual or audible representation.

Collections of both digitized physical objects and much born-digital content benefit from a standardized description of their structure, layout, and presentation mode. This document specifies this standardized description. Many different rich and dynamic user experiences can be implemented, presenting content from across collections and institutions.

A compound object may comprise a series of... [as before]

(and structured -> compound later)

General point

• I've found that describing a Manifest as a "markup document for a digital object that happens to be written in JSON" is really useful for developers, for the "a-ha" moment. It would be good to get this across in the spec intro somehow.

2. "Content resources" ? Or lower case as it's not a class? In 2.2 we have Content?

Lower case I think, but 2.2 is a bit problematic in its use of "type". In 2.1 the headings describing each type are also the values of type (e.g., Canvas) but in 2.2 the headings are (mostly) the conceptual name, especially Content, which can be many types. Is 2.2. actually "Additional Resources"? hmm...

2.1. (Collection) Maybe just:-

Collection

An ordered list of Manifests, and/or further Collections. Collections allow Manifests and child Collections to be grouped in a hierarchical structure for presentation, which can be for of generating navigation, showing dynamic results from a search, or providing fixed sets of related resources for any other purpose.

...and rely on later definitions (and their examples) to make it clear that "descriptive information" can be used (the spec reader would hope so!)

(Comments)

2.1 "Each Manifest describes how to present a single object such as a book, a statue or a music album."

• Well usually... but this isn't a requirement. Maybe just the addition of the word "usually"...
  The intent of the spec, and community practice, is that a Manifest loosely models a thing-in-hand; as a presentation spec that "thing" is out of scope.

cf. 5.2: "The Manifest resource typically represents a single object..."

3 (intro)

• The last para of the intro starts to define "client" a little (although the word has already been used earlier). Do we need to define what we mean by client a bit more formally? Perhaps even in 1.2.? ...When we say a client MUST... we really mean this...

• Normative requirements of properties. The now standardised representation of these, as a list included in each property, is verbose but clear, and is necessary. But... I wonder if there's a way of making them less visually intrusive? They break up the reading flow through the properties in the spec. Some visual styling that boxes them, so they are clear and present when referring to the spec, but out of the way when reading the spec.

• 3.1 summary Do we need to be clearer about what clients should do with metadata vs summary?

• rights

The value must be a string. If the value is drawn from Creative Commons or RightsStatements.org, then the string must be a URI defined by that specification.

Is that para necessary? Given what's been said already.

3.1.requiredStatement - that the +publishing organization deems ... ?
👍

3.1.provider - here "string that contains a URI", compare to rights where "string must be a URI". Prefer be a, not contain a.
👍

3.1.thumbnail - is "external resource" necessary to specify? Just resource? Probably comes from it being previously under external links in 3.3.1

A content resource, such as a small image or short audio clip, that represents the...

3.1.thumbnail - images and video_s_ ?

Doesn't read oddly as-is to me. Can we appeal to a higher authority for style?

3.thumbnail - In Canvas we use "representation" meaning the view. Ambiguous with web architecture use of representation?

Or:
A Canvas SHOULD have the thumbnail property if there is more than one Canvas

3.1. navdate - is "a time-based user interface" now ambiguous that we have temporal content resources? Change to 'date' based?

date-based is ambiguous too, but better, and sufficient here, and echoes nav_Date_

3.1.placeholder/accompanying Canvas value definition should define the value of type to be Canvas?
3.3.1.logo Similarly logo should define the value of type to be Image? (c.f. supplementary)
yes...

For the two xxxCanvas:

The value MUST be a JSON object with the id and type properties, and may have other properties of Canvases. The type MUST be Canvas

3.2.id is the bold for embedded and referenced needed?
No, as not bold elsewhere other than original definition.

3.2.type Does the table need a title or further reference, other than the second para in the prose?
Or move the table up to follow this para directly?

3.2.format -- should the note be called out as a note block, or is plain text sufficient?
Seems too small to draw too much attention to itself with a note block.

3.3.1.* -- drop "external" ?
👍

3.3.1.seeAlso -- "Other IIIF resources, such as a related Manifest, are valid targets for seeAlso. " Is that really true??
I think it is; if it wasn't I'd need another property. One use case here was for a manifest M' to link to manifest M, where M' was derived from M in some way, or is some other represention of it.

Use cases

• other digitisations of the same object, or a different manifestation <- expression of the same work
• We use this on IDA to link to the manifest for the microfilm roll(s) the derived manifest was assembled from. This is arguably partOf too, but not quite!
• generally, seeAlso refined by a profile is useful for inter-IIIF links.

3.3.2 -- has the wrong label of 3.4.2
And there's no 3.5 either!
Both of those are like that in published alpha as well, so not (as I first worried) a recent merge messup.

3.3.2.partOf -- is it clear that this is an external but IIIF resource, rather than within a single manifest document?
Current text allows it be within the manifest ("it might retrieve the containing resource, if it is not embedded in the current representation")

• Do we care if:

• People assert IIIF resources to be partOf non-IIIF resources?

• People assert non-IIIF resources to be partOf other non-IIIF resources?

• People assert non-IIIF resources to be partOf IIIF resources?

  5.* often have summaries of the required and recommended properties, but they're not complete. They should either be removed or cross-checked.

I don't think they should be removed, but they should have some catch-all formulation after the important usages have been called out, that acknowledges the full range of possibilities can be seen in the table.

[azaroth42]

Do we need to define what we mean by client a bit more formally? Perhaps even in 1.2.?

I think 1.2 would be a more formal place for the definition, but that by removing it from 3, the chances that the people who need to read it actually /do/ read it is reduced. Also, we don't define a bunch of other low level terms like API and whatever.

So I would leave it as is, rather than trying to be more explicit.

Normative requirements of properties [...] a way of making them less visually intrusive?

Lets split out style from content changes to a different issue?

Do we need to be clearer about what clients should do with metadata vs summary?

I think the first sentence of summary is pretty clear?

If the value is drawn from Creative Commons or RightsStatements.org, then the string must be a URI defined by that specification.

I think it's useful to repeat it, as readers might skim the paragraph and go straight to the definition of the syntax that they're used to from all the other properties.

3.1.thumbnail - images and video_s_ ?

I would read image content / video content, or images / videos meaning the files.

[azaroth42]

3.2.type Does the table need a title or further reference, other than the second para in the prose?
Or move the table up to follow this para directly?

Compare all of the other tables which are at the end of their sections and also the tables in the Image API. I think we should defer and compare across the other tables.

• People assert IIIF resources to be partOf non-IIIF resources?
• People assert non-IIIF resources to be partOf other non-IIIF resources?
• People assert non-IIIF resources to be partOf IIIF resources?

I think all of those are fine, but non-IIIF to non-IIIF is a bit out of scope, if not going to break anything.

[azaroth42]

What's the use case for asserting partOf to a resource that's already in the document? A graph, rather than a tree?

[azaroth42]

Having put the format/formats paragraph into a .note class, it looks really terrible due to the bullet list and example and note all having different indents. Taking it out.

[azaroth42]

Closed by #1850