Specification: Questions and clarifications for 1.2 text

[elichad]

Questions and suggestions that have come up for me while proofreading the spec. There will probably be more as I continue...

1. In structure.md, L201:

   An RO-Crate packaged with BagIt may be referencing external files which are not present in the RO-Crate Root hierarchy until the BagIt has been completed. This method can be used for files that are large, require authentication or otherwise inconvenient to transfer with the RO-Crate, but which should nevertheless still be considered part of the payload.

   Not clear to me what "This method" refers to - specifically the BagIt packaging method, or the general guidance on referencing external files?

2. Under Self-describing and self-contained (Attached RO-Crates), the last few paragraphs (from "While RO-Crate is well catered for..." onward) are not incorrect, but seem old/out of place relative to the sections before. Could we add a "Summary" heading or similar just above these?

   • (Noting that this cross-reference would also need updating if so)

3. metadata.md, L162

   As of 2024-05-23, the CodeMeta URIs do not resolve correctly, but are used here to match the Codemeta JSON-LD context https://w3id.org/codemeta/3.0 (issue #275). The CodeMeta terms maintainer and funding are not mapped, as these are already defined by schema.org.

   Is this still true? If so, update the date to the (pre-)release date.

4. root-data-entity.md, L39

   An RO-Crate is described using JSON-LD by an RO-Crate Metadata Document. As explained in section RO-Crate structure this may be stored in an RO-Crate Metadata File. In this section we describe the format of the JSON-LD document.

   Suggest this line be moved to the top of the Metadata section, as it would fit better there.

5. Required Root Data Entity properties have been a point of confusion:
   

   ro-crate/docs/_specification/1.2-DRAFT/root-data-entity.md

   Lines 131 to 137 in 4fc0b3a

   	The _Root Data Entity_ MUST have the following properties:
   	* `@type`: MUST be [Dataset] or an array that contains `Dataset`
   	* `@id`: SHOULD be the string `./` or an absolute URI (see [below](#root-data-entity-identifier))
   	* `name`: SHOULD identify the dataset to humans well enough to disambiguate it from other RO-Crates
   	* `description`: SHOULD further elaborate on the name to provide a summary of the context in which the dataset is important.
   	* `datePublished`: MUST be a single string value in [ISO 8601 date format][DateTime], SHOULD be specified to at least the precision of a day, and MAY be a timestamp down to the millisecond.

   
   Suggest changing the first line here to "The Root Data Entity MUST have all of the properties listed below. Each property also has requirements that apply to its value:"

6. data-entities.md - the "Encoding file paths" section is duplicated, once under "Core Metadata for Data Entities" (L240) and once under "Web-based Data Entities" (L357). Which copy should be removed?

7. Suggest that Referencing RO-Crates be its own section on the Data Entities page, rather than being nested under "Web-based Data Entities", as it is a long section and includes cases where the nested crates aren't web-based. (Won't affect cross-references as long as the heading names are unchanged.)

8. In the example from Profiles of nested crates the profile is given with a version, not a generic identifier. Is this ok/encouraged? It seems odd for it to be fine for profiles (unless a generic is not available) when we require that the base spec MUST be versionless in the same situation.

[ptsefton]

1. This method here is referring to "may be referencing external files which are not present in the RO-Crate Root hierarchy until the BagIt has been completed."

2. Yep good idea

3. @stain?

4. Yep

5. Yep

6. Remove the second one

7. Good idea

8. @stain??