diff --git a/docs/_includes/references.liquid b/docs/_includes/references.liquid index 31f61f6f..6051b338 100644 --- a/docs/_includes/references.liquid +++ b/docs/_includes/references.liquid @@ -175,7 +175,10 @@ and is also rendered into the end of the PDF. [IndividualProduct]: http://schema.org/IndividualProduct [instrument]: http://schema.org/instrument [keywords]: http://schema.org/keywords +[latitude]: http://schema.org/latitude [license]: http://schema.org/license +[longitude]: http://schema.org/longitude +[mainEntity]: http://schema.org/mainEntity [memberOf]: http://schema.org/memberOf [name]: http://schema.org/name [object]: http://schema.org/object @@ -185,6 +188,7 @@ and is also rendered into the end of the PDF. [relatedItem]: http://schema.org/relatedItem [result]: http://schema.org/result [sameAs]: http://schema.org/sameAs +[spatialCoverage]: http://schema.org/spatialCoverage [sdLicense]: http://schema.org/sdLicense [sdPublisher]: http://schema.org/sdPublisher [sdDatePublished]: http://schema.org/sdDatePublished diff --git a/docs/_specification/1.2-DRAFT/appendix/changelog.md b/docs/_specification/1.2-DRAFT/appendix/changelog.md index f4523765..fcb4c406 100644 --- a/docs/_specification/1.2-DRAFT/appendix/changelog.md +++ b/docs/_specification/1.2-DRAFT/appendix/changelog.md @@ -63,7 +63,7 @@ excerpt: List of changes in releases of this specifications * **Note**: The RO-Crate metadata file is renamed to `ro-crate-metadata.json` to facilitate use of JSON editors. [#82](https://github.com/ResearchObject/ro-crate/issues/82) [#84](https://github.com/ResearchObject/ro-crate/issues/84) * [Data entities](../data-entities) can reference external resources with absolute URI [#74](https://github.com/ResearchObject/ro-crate/issues/74) * Added section on considerations for [Web-based Data Entities](../data-entities#web-based-data-entities) [#74](https://github.com/ResearchObject/ro-crate/issues/74) - * The [root dataset](../root-data-entity#direct-properties-of-the-root-data-entity) is no longer required to be `./` [#74](https://github.com/ResearchObject/ro-crate/issues/74) + * The [Root Data Entity](../root-data-entity#direct-properties-of-the-root-data-entity) is no longer required to be `./` [#74](https://github.com/ResearchObject/ro-crate/issues/74) * [RO-Crate Root](../structure) directory no longer requires payload files [#74](https://github.com/ResearchObject/ro-crate/issues/74) * [Workflows and scripts](../workflows) section now aligned with [BioSchemas ComputationalWorkflow profile](https://bioschemas.org/profiles/ComputationalWorkflow/0.5-DRAFT-2020_07_21/) [#81](https://github.com/ResearchObject/ro-crate/issues/81) [#100](https://github.com/ResearchObject/ro-crate/pull/100) * Added section [Programming with JSON-LD](implementation-notes#programming-with-json-ld) and note that `@type` might be an array [#85](https://github.com/ResearchObject/ro-crate/issues/85) diff --git a/docs/_specification/1.2-DRAFT/appendix/relative-uris.md b/docs/_specification/1.2-DRAFT/appendix/relative-uris.md index 266f86fb..dd5e20a9 100644 --- a/docs/_specification/1.2-DRAFT/appendix/relative-uris.md +++ b/docs/_specification/1.2-DRAFT/appendix/relative-uris.md @@ -129,17 +129,17 @@ If the new Detached RO-Crate is not meant as a snapshot of the corresponding Att Converting a Detached Crate to an Attached Crate can mean multiple things depending on intentions, and may imply an elaborate process. -First, check if the Root Dataset already have a [distribution download](../data-entities#directories-on-the-web-dataset-distributions) listed, in which case that can be retrieved as the corresponding Attached Crate. +First, check if the Root Data Entity already have a [distribution download](../data-entities#directories-on-the-web-dataset-distributions) listed, in which case that can be retrieved as the corresponding Attached Crate. To archive a snapshot of an Detached Crate's metadata, keeping all data entities [web-based](../data-entities#web-based-data-entities): * Crate a new folder as the _RO-Crate Root_, save the _RO-Crate Metadata Document_ as the _RO-Crate Metadata File_ according to [Attached RO-Crate](../structure#attached-ro-crate) structure * Copy the absolute `@id` to become an `identifier` according to recommendations for [Root Data Entity identifier](../root-data-entity#root-data-entity-identifier) -* Change the `@id` of the root dataset to `./` and update all references to it, including from the [Metadata Descriptor](../root-data-entity#ro-crate-metadata-descriptor) +* Change the `@id` of the Root Data Entity to `./` and update all references to it, including from the [Metadata Descriptor](../root-data-entity#ro-crate-metadata-descriptor) If the new Attached Crate is intended as a _fork_ that will evolve independently of the Detached Crate, then: * Delete the `identifier`, add the previous `@id` as `isBasedOn` * Delete/update `datePublished` and `publisher` -* Add yourself as `author` or `contributor` to the Root Dataset +* Add yourself as `author` or `contributor` to the Root Data Entity * Add records of [changes to the Crate](../provenance#recording-changes-to-ro-crates) diff --git a/docs/_specification/1.2-DRAFT/contextual-entities.md b/docs/_specification/1.2-DRAFT/contextual-entities.md index 2dd67f52..b386ae46 100644 --- a/docs/_specification/1.2-DRAFT/contextual-entities.md +++ b/docs/_specification/1.2-DRAFT/contextual-entities.md @@ -51,11 +51,11 @@ RO-Crate distinguishes between _contextual entities_ and _data entities_. Some contextual entities can also be considered data entities -- for instance the [license](#licensing-access-control-and-copyright) property refers to a [CreativeWork] that can reasonably be downloaded, however a license document is not usually considered as part of research outputs and would therefore typically not be included in [hasPart] on the [root data entity](root-data-entity). -{% include callout.html type="tip" content="Files in the _RO-Crate Root_ are not necessarily data entities -- the [RO-Crate Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor) is a file in the _RO-Crate Root_, but is considered a _Contextual Entity_ as it is describing the RO-Crate, rather than being part of it. On the other hand, the [Root Data Entity](root-data-entity#root-data-entity) is a data entity within its own metadata file." %} +Likewise, some data entities may also be described as contextual entities, for instance a `File` that is also a [ScholarlyArticle]. In such cases the _contextual data entity_ MUST be described as a single JSON-LD object in the RO-Crate Metadata JSON-LD `@graph` and SHOULD list both relevant data and contextual types in a `@type` array. -Likewise, some data entities may also be described as contextual entities, for instance a `File` that is also a [ScholarlyArticle]. In such cases the _contextual data entity_ MUST be described as a single JSON object in the RO-Crate Metadata JSON `@graph` and SHOULD list both relevant data and contextual types in a `@type` array. +{% include callout.html type="tip" content="Files in the _RO-Crate Root_ are not necessarily data entities -- the [RO-Crate Metadata Descriptor](root-data-entity#ro-crate-metadata-descriptor) is a file in the _RO-Crate Root_, but is considered a _Contextual Entity_ as it is describing the RO-Crate, rather than being part of it. On the other hand, the [Root Data Entity](root-data-entity#root-data-entity) is a data entity within its own metadata file." %} -The RO-Crate Metadata JSON `@graph` MUST NOT list multiple entities with the same `@id`; behaviour of consumers of an RO-Crate encountering multiple entities with the same `@id` is undefined. +The RO-Crate Metadata JSON-LD `@graph` MUST NOT list multiple entities with the same `@id`; behaviour of consumers of an RO-Crate encountering multiple entities with the same `@id` is undefined. ## Identifiers for contextual entities @@ -74,14 +74,15 @@ See the [appendix on JSON-LD identifiers](appendix/jsonld#describing-entities-in ## People -A core principle of Linked data is to use URIs to identify important entities such as people. The following is the minimum recommended way of representing an [author] of an RO-Crate. The [author] property MAY also be applied to a directory ([Dataset]), a [File] or other [CreativeWork] entities. +A core principle of Linked Data is to use URIs to identify important entities such as people. The following is the minimum recommended way of representing an [author] of an RO-Crate. The [author] property MAY also be applied to a directory ([Dataset]), a [File] or other [CreativeWork] entities. ```json { "@type": "Dataset", "@id": "./", + "...": "...", "author": {"@id": "https://orcid.org/0000-0002-8367-6908"} -} +}, { "@id": "https://orcid.org/0000-0002-8367-6908", "@type": "Person", @@ -97,13 +98,14 @@ Note the string _value_ for the organizational affiliation. This SHOULD be impro ## Organizations as values -An [Organization] SHOULD be the value for the [publisher] property of a [Dataset] or [ScholarlyArticle] or [affiliation] property of a [Person]. +An [Organization] SHOULD be the value for the [publisher] property of a [Dataset] or [ScholarlyArticle]. ```json { "@type": "Dataset", "@id": "./", + "...": "...", "publisher": {"@id": "https://ror.org/03f0f6041"} } @@ -121,6 +123,7 @@ An [Organization] SHOULD also be used for a [Person]'s [affiliation] property. { "@type": "Dataset", "@id": "./", + "...": "...", "publisher": {"@id": "https://ror.org/03f0f6041"}, "author": {"@id": "https://orcid.org/0000-0002-3545-944X"} }, @@ -139,8 +142,6 @@ An [Organization] SHOULD also be used for a [Person]'s [affiliation] property. ``` - - ## Contact information An RO-Crate SHOULD have contact information, using a contextual entity of type [ContactPoint]. Note that in Schema.org [Dataset] does not currently have the corresponding [contactPoint] property, so the contact point would need to be given through a [Person] or [Organization] contextual entity which are related to the Dataset via a [author] or [publisher] property. @@ -150,6 +151,7 @@ An RO-Crate SHOULD have contact information, using a contextual entity of type [ { "@id": "./", "@type": "Dataset", + "...": "...", "author": {"@id": "https://orcid.org/0000-0001-6121-5409"} }, { @@ -186,6 +188,7 @@ For example: { "@id": "./", "@type": "Dataset", + "...": "...", "citation": {"@id": "https://doi.org/10.1109/TCYB.2014.2386282"} } ``` @@ -324,7 +327,7 @@ To associate a research project with a [Dataset], the _RO-Crate JSON-LD_ SHOULD }, { "@id": "https://ror.org/03f0f6041", - "@type": "Organisation", + "@type": "Organization", "identifier": "https://ror.org/03f0f6041", "name": "University of Technology Sydney" }, @@ -411,6 +414,7 @@ To express the metadata license is different from the _Root Data Entity_, expand { "@id": "./", "@type": "Dataset", + "...": "...", "license": { "@id": "https://creativecommons.org/licenses/by/4.0/" } @@ -418,7 +422,7 @@ To express the metadata license is different from the _Root Data Entity_, expand ``` -If no explicit `license` is expressed on the _RO-Crate Metadata Descriptor_, the `license` expressed on the _Root Data Entity_ apply also on the RO-Crate metadata. +If no explicit `license` is expressed on the _RO-Crate Metadata Descriptor_, the `license` expressed on the _Root Data Entity_ applies also on the RO-Crate metadata. ## Extra metadata such as Exif @@ -457,8 +461,7 @@ To include EXIF, or other data which can be encoded as property/value pairs, add ## Places -To associate a [Data Entity](data-entities) with a _Contextual Entity_ representing a geographical location or region the entity SHOULD have a property of [contentLocation] or [spatialCoverage] with a value of type [Place]. - +To associate a [Data Entity](data-entities) with a _Contextual Entity_ representing a geographical location or region, the entity SHOULD have a property of [contentLocation] or [spatialCoverage] with a value of type [Place]. To express point or shape geometry it is recommended that a `geo` property on a [Place] entity SHOULD link to a [Geometry] entity, with an [asWKT] property that expresses the point or shape in [Well Known Text (WKT)](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format. This example is a point, `POINT ($longitude, $latitude)`, but other asWKT primitives, `LINESTRING` & `POLYGON` SHOULD be used as required. @@ -469,6 +472,7 @@ This example shows how to define a place, using a [geonames] ID: { "@id": "./", "@type": "Dataset", + "...": "...", "outputOf": "RO-Crate", "contact": { "@id": "https://orcid.org/0000-0002-3545-944X" @@ -496,22 +500,19 @@ This example shows how to define a place, using a [geonames] ID: } ``` -**Tip**: To find the `@id` and `identifier` corresponding to a GeoNames HTML page like click its `.rdf` button to find the identifier referred from : - -```xml - - -``` - -**Tip**: Note the use of a JSON-LD blank node identifier here (starting with `_:`) - this indicates to an RO-Crate presentation application that the entity does not stand in its own right, and may be displayed inline (in this case as a map). +{% include callout.html type="tip" content='To find the `@id` and `identifier` corresponding to a GeoNames HTML page like , click its `.rdf` button to download the RDF metadata (). In the RDF metadata, find the line that looks like the following: +``. The part in the quotes is the identifier (in this case, ) . +' %} -**Tip**: It is considered best practice to include the explicit mentioning of the CRS (Coordinate Reference System) identified through its opengis URI at the start of the `asWKT` field. This provides the essential context to have the numbers is the remainder of the string correctly be plotted on te map. Note however that many GIS related tooling expects that information to be fed in via a seperate config setting or API call. So handling these strings in any app that interacts with such systems might require some extra processing. +{% include callout.html type="tip" content="Note the use of a JSON-LD [blank node](https://www.w3.org/TR/rdf11-concepts/#dfn-blank-node) identifier here (starting with `_:`) - this indicates to an RO-Crate presentation application that the entity does not stand in its own right, and may be displayed inline (in this case as a map)." %} -**NOTE**: Any of the schema.org geographical classes and entities MAY be used on a [Place] element to describe geographical points and shapes, and previous versions of this specification did show examples of using [latitude] and [longitude] properties and entities such as [GeoCoordinates], however this results in very verbose JSON-LD and there is some imprecision in the schema.org specification that makes this approach hard to implement in RO-Crate applications for analysis or presentation of crates. We found that developers were resorting to embedding escaped [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) as string values in RO-Crate; WKT format is more compact and easier to implement and is recommended for use in RO-Crate as shown above. +{% include callout.html type="tip" content="It is considered best practice to include the explicit mentioning of the CRS (Coordinate Reference System) identified through its opengis URI at the start of the `asWKT` field. This provides the essential context to have the numbers in the remainder of the string correctly be plotted on the map. Note, however, that many GIS related tools expect that information to be fed in via a separate configuration setting or API call. Handling these strings in any app that interacts with such systems might therefore require some extra processing." %} +{% include callout.html type="note" content="Any of the schema.org geographical classes and entities MAY be used on a [Place] element to describe geographical points and shapes, and previous versions of this specification did show examples of using [latitude] and [longitude] properties and entities such as [GeoCoordinates]. However, this results in very verbose JSON-LD, and there is some imprecision in the Schema.org specification that makes this approach hard to implement in applications for analysis or presentation of RO-Crates. We found that developers were resorting to embedding escaped [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) as string values in RO-Crate; instead of this, WKT format is more compact and easier to implement and is recommended for use in RO-Crate as shown above." %} + ## Subjects & keywords -Subject properties (equivalent to a Dublin Core Subject) on the [root data entity](root-data-entity) or a [data entity](data-entities) MUST use the [about] property. +Subject properties (equivalent to a [Dublin Core Subject](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/subject/)) on the [root data entity](root-data-entity) or a [data entity](data-entities) MUST use the [about] property. Keyword properties MUST use [keywords]. Note that by Schema.org convention, keywords are given as a single JSON string, with individual keywords separated by commas. @@ -541,9 +542,9 @@ To describe the _time period_ which an RO-Crate [Data Entity](data-entities) (or A [File] or any other entity MAY have a [thumbnail] property which references another file. -For example, the below [RepositoryObject] is related to four files which are all versions of the same image (via [hasFile]) one of which is a thumbnail. The thumbnail MUST be included in the RO-Crate. +For example, the below [RepositoryObject] is related to four files which are all versions of the same image (via [hasFile]), one of which is a thumbnail. The thumbnail MUST be included in the RO-Crate. -If [thumbnail]s are incidental to the data set, they need not be referenced by [hasPart] or [hasFile] relationships. but must be in the BagIt manifest if in a _Bagged RO-Crate_. +If [thumbnail]s are incidental to the data set, they need not be referenced by [hasPart] or [hasFile] relationships, but they must be in the BagIt manifest if in a [_Bagged RO-Crate_](appendix/implementation-notes#adding-ro-crate-to-bagit). ```json diff --git a/docs/_specification/1.2-DRAFT/crate-focus.md b/docs/_specification/1.2-DRAFT/crate-focus.md index 876b358f..072565b4 100644 --- a/docs/_specification/1.2-DRAFT/crate-focus.md +++ b/docs/_specification/1.2-DRAFT/crate-focus.md @@ -3,7 +3,7 @@ title: The focus of an RO-Crate redirect_from: - /1.2-DRAFT/crate-focus excerpt: | - In addition to simple data packaging, Crates may have a "main" entry point or topic (referenced with a singleton `mainEntity` property), or function as a bundle of one or more Contextual Entities referenced via the `mentions` property. + In addition to simple data packaging, RO-Crates may have a "main" entry point or topic (referenced with a singleton `mainEntity` property), or function as a bundle of one or more Contextual Entities referenced via the `mentions` property. nav_order: 7 jekyll-mentions: false parent: RO-Crate 1.2-DRAFT @@ -28,15 +28,17 @@ parent: RO-Crate 1.2-DRAFT # The focus of an RO-Crate {#crate-focus} -In addition to simple data packaging, Crates may have a "main" entry point or topic (referenced with a singleton `mainEntity` property), or function as a bundle of one or more Contextual Entities referenced via the `mentions` property. +In addition to simple data packaging, RO-Crates may have a "main" entry point or topic (referenced with a singleton `mainEntity` property), or function as a bundle of one or more Contextual Entities referenced via the `mentions` property. -## Crates with a "main entity" +## RO-Crates with a "main entity" -An RO-Crate may have a single main entity that is considered the point, or focus of the crate. +An RO-Crate may have a single main entity that is considered the point, or focus of the RO-Crate. This may be referenced from the _Root Data Entity_ using the [mainEntity] property. -### Crates with a data entity as mainEntity +### RO-Crates with a data entity as `mainEntity` -In the [Workflow RO-Crate profile](https://www.researchobject.org/ro-crate/profiles.html#workflow-ro-crate-profile), where the `mainEntity` has a compound type `["File", "SoftwareSourceCode", "ComputationalWorkflow"]`, the use of `mainEntity` singles-out the workflow file from supporting files. +The focus of an RO-Crate may be a single _Data Entity_ supplemented by other data and/or contextual entities. + +For example, in the [Workflow RO-Crate profile](https://www.researchobject.org/ro-crate/profiles.html#workflow-ro-crate-profile), the use of `mainEntity` singles-out the workflow file from supporting files. ```json { @@ -45,6 +47,7 @@ In the [Workflow RO-Crate profile](https://www.researchobject.org/ro-crate/profi "name": "Example Workflow", "description": "An example workflow RO Crate", "license": "Apache-2.0", + "datePublished": "2023-01-01", "mainEntity": { "@id": "example_workflow.cwl" }, @@ -62,18 +65,19 @@ In the [Workflow RO-Crate profile](https://www.researchobject.org/ro-crate/profi } ``` -### Crates with a contextual entity as mainEntity +### RO-Crates with a contextual entity as `mainEntity` -The focus of the RO-Crate may be a description of a _Contextual Entity_, for example in an RO-Crate used in a repository or encyclopedia where a RepositoryObject bundles together images and other files, but the main focus of the RO-Crate is on describing a person. +The focus of the RO-Crate may be a description of a _Contextual Entity_, for example in an RO-Crate used in a repository or encyclopedia where a `RepositoryObject` bundles together images and other files, but the main focus of the RO-Crate is on describing a person. ```json { "@id": "./", "@type": ["Dataset", "RepositoryObject"], "name": "Reibey, Mary (1777 - 1855)", + "...": "...", "mainEntity": { "@id": "https://en.wikipedia.org/wiki/Mary_Reibey" - } + }, "hasPart" : [ {"@id": "photo1.jpg"}, {"@id": "photo2.jpg"} @@ -88,11 +92,11 @@ The focus of the RO-Crate may be a description of a _Contextual Entity_, for exa } ``` -## Crates which describe _Contextual Entities_ +## RO-Crates which focus on multiple _Contextual Entities_ -RO-Crates may describe _Contextual Entities_ which are linked to the [Root Dataset](root-data-entity) via `mentions` relationships. +RO-Crates may describe _Contextual Entities_ which are linked to the [Root Data Entity](root-data-entity) via `mentions` relationships. -For example, RO-Crates can be used as containers for schema.org-style vocabularies (here also extending the [RO-Crate JSON-LD context](appendix/jsonld.html#ro-crate-json-ld-context) to define the namespace for `txc:`): +For example, RO-Crates can be used as containers for Schema.org-style vocabularies (here also [extending the RO-Crate JSON-LD context](appendix/jsonld.html#ro-crate-json-ld-context) to define the namespace for `txc:`): ```json { "@context": [ @@ -146,66 +150,68 @@ For example, RO-Crates can be used as containers for schema.org-style vocabulari ``` -The following example shows both a `mainEntity` which is a _Data Entity_ and a _Contextual Entity_ which is a test suite (`#test1`). +The following example shows how both `mainEntity` and `mentions` can be used together, in this case to describe a workflow with a test suite: + * the `mainEntity` is the workflow file, a _Data Entity_ + * the test suite `#test1` is a _Contextual Entity_ highlighted using `mentions`. ```json +{ + "@id": "./", + "@type": "Dataset", + "name": "sort-and-change-case", + "description": "sort lines and change text to upper case", + "license": "Apache-2.0", + "mainEntity": { + "@id": "sort-and-change-case.ga" + }, + "mentions": [ {"@id": "#test1"} ], + "hasPart": [ { - "@id": "./", - "@type": "Dataset", - "name": "sort-and-change-case", - "description": "sort lines and change text to upper case", - "license": "Apache-2.0", - "mainEntity": { - "@id": "sort-and-change-case.ga" - }, - "mentions": [ {"@id": "#test1"} ], - "hasPart": [ - { - "@id": "sort-and-change-case.ga" - }, - { - "@id": "test/test1/sort-and-change-case-test.yml" - } - ] - }, - { - "@id": "#test1", - "name": "test1", - "@type": "TestSuite", - "instance": [ - {"@id": "#test1_1"} - ], - "definition": {"@id": "test/test1/sort-and-change-case-test.yml"} - }, - { - "@id": "#test1_1", - "name": "test1_1", - "@type": "TestInstance", - "runsOn": {"@id": "#jenkins"}, - "url": "http://example.org/jenkins", - "resource": "job/tests/" - }, - { - "@id": "test/test1/sort-and-change-case-test.yml", - "@type": [ - "File", - "TestDefinition" - ], - "conformsTo": {"@id": "#planemo"} - }, - { - "@id": "#jenkins", - "@type": "TestService", - "name": "Jenkins", - "url": {"@id": "https://www.jenkins.io"} + "@id": "sort-and-change-case.ga" }, { - "@id": "#planemo", - "@type": "SoftwareApplication", - "name": "Planemo", - "url": {"@id": "https://github.com/galaxyproject/planemo"}, - "version": ">=0.70" + "@id": "test/test1/sort-and-change-case-test.yml" } + ] +}, +{ + "@id": "#test1", + "name": "test1", + "@type": "TestSuite", + "instance": [ + {"@id": "#test1_1"} + ], + "definition": {"@id": "test/test1/sort-and-change-case-test.yml"} +}, +{ + "@id": "#test1_1", + "name": "test1_1", + "@type": "TestInstance", + "runsOn": {"@id": "#jenkins"}, + "url": "http://example.org/jenkins", + "resource": "job/tests/" +}, +{ + "@id": "test/test1/sort-and-change-case-test.yml", + "@type": [ + "File", + "TestDefinition" + ], + "conformsTo": {"@id": "#planemo"} +}, +{ + "@id": "#jenkins", + "@type": "TestService", + "name": "Jenkins", + "url": {"@id": "https://www.jenkins.io"} +}, +{ + "@id": "#planemo", + "@type": "SoftwareApplication", + "name": "Planemo", + "url": {"@id": "https://github.com/galaxyproject/planemo"}, + "version": ">=0.70" +} ``` {% include references.liquid %} diff --git a/docs/_specification/1.2-DRAFT/data-entities.md b/docs/_specification/1.2-DRAFT/data-entities.md index b0086282..a556907d 100644 --- a/docs/_specification/1.2-DRAFT/data-entities.md +++ b/docs/_specification/1.2-DRAFT/data-entities.md @@ -42,7 +42,7 @@ The data entities can be further described by referencing [contextual entities]( ## Referencing files and folders from the Root Data Entity -Where files and folders are represented as _Data Entities_ in the RO-Crate JSON-LD, these MUST be linked to, either directly or indirectly, from the [Root Data Entity](root-data-entity) using the [hasPart] property. Directory hierarchies MAY be represented with nested [Dataset] _Data Entities_, or the Root Dataset MAY refer to files anywhere in the hierarchy using [hasPart]. +Where files and folders are represented as _Data Entities_ in the RO-Crate JSON-LD, these MUST be linked to, either directly or indirectly, from the [Root Data Entity](root-data-entity) using the [hasPart] property. Directory hierarchies MAY be represented with nested [Dataset] _Data Entities_, or the Root Data Entity MAY refer to files anywhere in the hierarchy using [hasPart]. _Data Entities_ representing files MUST have `"File"` as a value for `@type`. `File` is an RO-Crate alias for . The term _File_ includes: - _Attached_ resources where `@id` is a URI (path) relative to the _RO-Crate Root_ which MUST resolve to a file. diff --git a/docs/_specification/1.2-DRAFT/profiles.md b/docs/_specification/1.2-DRAFT/profiles.md index 825c2f7a..d8f13a13 100644 --- a/docs/_specification/1.2-DRAFT/profiles.md +++ b/docs/_specification/1.2-DRAFT/profiles.md @@ -27,27 +27,27 @@ parent: RO-Crate 1.2-DRAFT # RO-Crate profiles {#profiles} -While RO-Crates can be considered general-purpose containers of arbitrary data and open-ended metadata, in practical use within a particular domain, application or framework, it will be beneficial to further constrain RO-Crate to a specific **profile**: a set of conventions, types and properties that one minimally can require and expect to be present in that subset of RO-Crates. +While RO-Crates can be considered general-purpose containers of arbitrary data and open-ended metadata, in practical use within a particular domain, application or framework, it will be beneficial to further constrain RO-Crate to a specific **profile**: a set of conventions, types and properties that one can minimally require and expect to be present in that subset of RO-Crates. -Defining and conforming to such a profile enables reliable programmatic consumption of an RO-Crate’s content, as well as consistent creation, e.g. a form in a user interface containing the required types and properties, and likewise a rendering of an RO-Crate can easier make rich UI components if it can reliably assume for instance that the [`Person`](contextual-entities#people) always has an `affiliation` to a [`Organization`](contextual-entities#organizations-as-values) which has a `url` - a restriction that may not be appropriate for all types of RO-Crates. +Defining and conforming to such a profile enables reliable programmatic consumption of an RO-Crate’s content, as well as consistent creation, e.g. via a form in a user interface containing the required types and properties. Likewise, a rendering of an RO-Crate can more easily make rich UI components if it can reliably assume, for instance, that a [`Person`](contextual-entities#people) always has an `affiliation` to a [`Organization`](contextual-entities#organizations-as-values) which has a `url` - a restriction that may not be appropriate for all types of RO-Crates. -As such RO-Crate Profiles can be considered a _duck typing_ mechanism for RO-Crates, but also as a classifier to indicate the crate's purpose, expectations and focus. +As such, RO-Crate profiles can be considered a _duck typing_ mechanism for RO-Crates, but also as a classifier to indicate the crate's purpose, expectations, and focus. ## Publishing an RO-Crate profile -An _RO-Crate profile_ is identified with a **Profile URI**. +An _RO-Crate profile_ is identified with a **profile URI** with the following constraints: -Recommendations: * The profile URI MUST resolve to a human-readable _profile description_ (e.g. a HTML web page) - The profile URI MAY have a corresponding machine-readable [_Profile Crate_](#profile-crate) * The profile URI SHOULD be a _permalink_ (persistent identifier) - e.g. starting with or * The profile URI SHOULD be _versioned_ with [`MAJOR.MINOR`][semver], e.g. `http://example.com/image-profile-2.4` -* The profile description SHOULD use key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL as described in [RFC 2119]. -Suggestions: +The profile description declares the set of conventions to be used. + +* The profile description SHOULD use key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL as described in [RFC 2119]. * The profile MAY require/suggest which `@type` of [data entities](data-entities) and/or [contextual entities](contextual-entities) are expected. -* The profile MAY require/suggest _properties_ expected per type of entity (e.g. _"Each [CreativeWork] must declare a [license]"_) +* The profile MAY require/suggest _properties_ expected per type of entity (e.g. _"Each [CreativeWork] MUST declare a [license]"_) * The profile MAY require/suggest a particular [version of RO-Crate](https://www.researchobject.org/ro-crate/specification.html). * The profile MAY recommend [RO-Crate extensions](appendix/jsonld#extending-ro-crate) with domain-specific terms and vocabularies. * The profile MAY require/suggest a particular [JSON-LD context](appendix/jsonld?highlight=@context#ro-crate-json-ld-context). @@ -56,7 +56,7 @@ Suggestions: ## Declaring conformance of an RO-Crate profile -RO-Crate can describe a profile by adding it as an [contextual entity](contextual-entities): +An RO-Crate can describe a profile by adding it as an [contextual entity](contextual-entities): ```json { @@ -67,13 +67,14 @@ RO-Crate can describe a profile by adding it as an [contextual entity](contextua } ``` -The contextual entity for a profile: +In the contextual entity for a profile: -* The `@type` SHOULD be an array. The `@type` MUST include [Profile]. -* The `@type` SHOULD include `CreativeWork` (indicating a Web Page) or `Dataset` (indicating a Profile Crate). -* SHOULD have an absolute URI as `@id` -* SHOULD have a descriptive [name] -* MAY declare [version], preferably according to [Semantic Versioning][semver] +* The `@type` SHOULD be an array. +* The `@type` MUST include [Profile]. +* The `@type` SHOULD include `CreativeWork` (indicating a Web Page) or `Dataset` (indicating a [Profile Crate](#profile-crate)). +* The entity SHOULD have an absolute URI as `@id` +* The entity SHOULD have a descriptive [name] +* The entity MAY declare [version], preferably according to [Semantic Versioning][semver] RO-Crates that are _conforming to_ (or intending to conform to) such a profile SHOULD declare this using `conformsTo` on the [root data entity](root-data-entity): @@ -88,19 +89,19 @@ RO-Crates that are _conforming to_ (or intending to conform to) such a profile S It is valid for a crate to conform to multiple profiles, in which case `conformsTo` is an unordered array. -Note that as profile conformance is declared on the RO-Crate Root (`./` in this example), the profile applies to the whole RO-Crate, and may cover aspects beyond the crate's metadata file (e.g. identifiers, packaging, purpose). +{% include callout.html type="note" content="Profile conformance is declared on the _Root Data Entity_ (`./` in this example), rather than on the _RO-Crate Metadata Descriptor_ (`ro-crate-metadata.json`) where conformance to the base RO-Crate specification is declared. This is because the profile applies to the whole RO-Crate, and may cover aspects beyond the crate's metadata file (e.g. identifiers, packaging, purpose)." %} ## Profile Crate -While the Profile URI `@id` must resolve to a human-readable _profile description_, it MAY additionally be made to [resolve](#how-to-retrieve-a-profile-crate) to a _Profile Crate_. +While the Profile URI `@id` MUST resolve to a human-readable _profile description_, it MAY additionally be made to [resolve](#how-to-retrieve-a-profile-crate) to a _Profile Crate_. -A **Profile Crate** is a type of RO-Crate that gathers resources which further define the profile in addition to the _profile description_. This allows formalizing an alternative profile description for machine-readability, for instance for validation, but also additional resources like examples. The rest of this subsection declares the content of this Profile Crate. +A **Profile Crate** is a type of RO-Crate that represents an RO-Crate profile. It gathers resources which further define the profile in addition to the _profile description_. This allows formalizing an alternative profile description for machine-readability (for instance for validation), and also additional resources like examples. The rest of this subsection declares the content of this Profile Crate. The Profile Crate `@id` declared within its own RO-Crate Metadata Document SHOULD be an absolute URI, and the corresponding reference from its RO-Crate Metadata Descriptor updated accordingly. -Within the Profile Crate, its [Root Data entity](root-data-entity) MUST declare `Profile` as an additional `@type`: +Within the Profile Crate, its [Root Data Entity](root-data-entity) MUST declare `Profile` as an additional `@type`: ```json { @@ -145,9 +146,10 @@ Within the Profile Crate, its [Root Data entity](root-data-entity) MUST declare } ``` -The rest of the [earlier requirements](#declaring-conformance-of-an-ro-crate-profile) for a Profile entity also apply here, adding: +The [earlier requirements](#declaring-conformance-of-an-ro-crate-profile) for a [Profile] entity also apply here. +In addition, in a Profile Crate the _Root Data Entity_: -* MUST reference the human readable _profile description_ as a data entity +* MUST reference the human-readable _profile description_ as a data entity using `hasPart` * SHOULD have an absolute URI as `@id` * SHOULD have a descriptive [name] * MAY declare [version], preferably according to [Semantic Versioning][semver] (e.g. `0.4.0`) @@ -160,21 +162,20 @@ The rest of the [earlier requirements](#declaring-conformance-of-an-ro-crate-pro ### How to retrieve a Profile Crate -To resolve a Profile URI to a machine-readable _Profile Crate_, follow the approaches of [retrieving an RO-Crate](data-entities#retrieving-an-ro-crate). - -If none of these approaches worked, then this profile probably does not have a corresponding Profile Crate. For human display of conformed profiles, display a hyperlink to its `@id` Web page, described by its `name`. +To resolve a profile URI to a machine-readable _Profile Crate_, follow the approaches of [retrieving an RO-Crate](data-entities#retrieving-an-ro-crate). +If none of these approaches worked, then this profile probably does not have a corresponding Profile Crate. For human display of the profile (e.g. when listing profiles another RO-Crate conforms to), display a hyperlink to its `@id` Web page, described by its `name`. #### Shared contextual entities from a Profile Crate -If an RO-Crate declares conformance to a given profile crate with `conformsTo` on its root data entity, contextual entities declared in the corresponding Profile Crate do _not_ need to be repeated in the conforming crate. +If an RO-Crate declares conformance to a given Profile Crate with `conformsTo` on its root data entity, contextual entities declared in the corresponding Profile Crate do _not_ need to be repeated in the conforming crate. -For instance, if a Profile Crate adds a `DefinedTerm` entity according to the [ad-hoc definitions](appendix/jsonld#adding-new-or-ad-hoc-vocabulary-terms), the term MAY be referenced in the conforming crate without making a contextual entity there. For archival purposes it MAY however still be preferrable to copy such entities across to each conforming crate. +For instance, if a Profile Crate adds a `DefinedTerm` entity according to the [ad-hoc definitions](appendix/jsonld#adding-new-or-ad-hoc-vocabulary-terms), the term MAY be referenced in the conforming crate without making a contextual entity there. For archival purposes it MAY however still be preferable to copy such entities across to each conforming crate. -{% include callout.html type="note" content="In the conforming crate, any terms defined in the profile using `DefinedTerm`, `rdfs:Class` and `rdf:Property` MUST either be used as full URIs matching the `@id`, or mapped to these URIs from the conforming crate's JSON-LD `@context`. Note that JSON-LD only expands keys from `@id` and `@type`." %} +It is RECOMMENDED that `@id` of such shared entities are absolute URIs on both sides to avoid resolving relative paths, and the profile's recommended [JSON-LD Context](#json-ld-context) used by conforming crates SHOULD have a mapping to the URIs, see section [Extending RO-Crate](appendix/jsonld#extending-ro-crate). -It is RECOMMENDED that `@id` of such shared entities are absolute URIs on both sides to avoid resolving relative paths, and that the profile's recommended [JSON-LD Context](#json-ld-context) used by conforming crates SHOULD have a mapping to the URIs, see section [Extending RO-Crate](appendix/jsonld#extending-ro-crate). +{% include callout.html type="note" content="In the conforming crate, any terms defined in the profile using `DefinedTerm`, `rdfs:Class` and `rdf:Property` MUST either be used as full URIs matching the `@id`, or mapped to these URIs from the conforming crate's JSON-LD `@context`. Note that JSON-LD only expands keys from `@id` and `@type`." %} #### Archiving Profile Crates @@ -204,7 +205,7 @@ This section defines the type of resources that should or may be included in the #### Declaring the role within the crate -In order for programmatic use of the Profile Crate to consume particular subresources, e.g. for validation, the _role_ of each entity SHOULD be declared by including them using `hasResource` to a `ResourceDescriptor` contextual entity that references the subresource using `hasResource`, as defined by the [Profiles Vocabulary]: +In order for programmatic use of the Profile Crate to consume particular subresources, e.g. for validation, the _role_ of each entity SHOULD be declared by including them using `hasResource` to a `ResourceDescriptor` contextual entity that references the subresource using `hasArtifact`, as defined by the [Profiles Vocabulary]: ```json { @@ -246,7 +247,7 @@ The [`ResourceDescriptor`](https://www.w3.org/TR/dx-prof/#Class:ResourceDescript } ``` -The referenced role do not need to be declared as a `DefinedTerm` contextual entity unless it differs from these recommended [predefined roles](https://www.w3.org/TR/dx-prof/#resource-roles-vocab): +The referenced role does not need to be declared as a `DefinedTerm` contextual entity unless it differs from these recommended [predefined roles](https://www.w3.org/TR/dx-prof/#resource-roles-vocab): ```json { @@ -305,9 +306,9 @@ The referenced role do not need to be declared as a `DefinedTerm` contextual ent } ``` -The examples in the rest of this document will list the data entities with a corresponding `ResourceDescriptor` entity, but for brevity not repeating the required `hasPart` and `hasResource` references from the root dataset. +The examples in the rest of this section will list the data entities with a corresponding `ResourceDescriptor` entity, but for brevity the required `hasPart` and `hasResource` references from the _Root Data Entity_ will not be repeated. -Below follows the suggested [data entities](data-entities) to include in a Profile Crate using `hasPart` and, if applicable, a corresponding `hasResource` to a `ResourceDescriptor`: +Below follows the suggested [data entities](data-entities) to include in a Profile Crate using `hasPart` and, if applicable, a corresponding `hasResource` to a `ResourceDescriptor`: #### Profile description entity @@ -380,12 +381,12 @@ A schema may formalize restrictions on the a graph-level (e.g. what types/properties) as well as serialization level (e.g. use of JSON arrays). -This interpretation of _schema_ assumes the resource somewhat describes the data structure, e.g. expected types and attributes the RO-Crate's JSON-LD. Use alternatively the role `http://www.w3.org/ns/dx/prof/role/validation` if the schema is primarily a set of constraint for validation purposes, or `http://www.w3.org/ns/dx/prof/role/vocabulary` for ontologies and term listings. +This interpretation of _schema_ assumes the resource somewhat describes the data structure, e.g. expected types and attributes in the RO-Crate's JSON-LD. Use alternatively the role `http://www.w3.org/ns/dx/prof/role/validation` if the schema is primarily a set of constraints for validation purposes, or `http://www.w3.org/ns/dx/prof/role/vocabulary` for ontologies and term listings. -Below are known schema types in their recommended media type, with suggested identifiers for the contextual entities of -[encodingFormat](data-entities#adding-detailed-descriptions-of-encodings) with type `Standard` and `conformsTo` with type `Profile`: +Below are known schema types and their recommended media type, with suggested identifiers for the contextual entities of +[encodingFormat](data-entities#adding-detailed-descriptions-of-encodings) with type `Standard` and [conformsTo] with type `Profile`: | Name | `encodingFormat` Media Type | `encodingFormat` URI | `conformsTo` URI | role | | -------------- | ------------------------- | -------------------------- | ---------- | @@ -547,7 +548,7 @@ context in the Profile Crate: "name": "RO-Crate JSON-LD Context", "encodingFormat": "application/ld+json", "conformsTo": {"@id": "http://www.w3.org/ns/json-ld#Context"}, - "version": "1.1.1" + "version": "1.2.0" }, { "@id": "http://www.w3.org/ns/json-ld#Context", @@ -557,7 +558,7 @@ context in the Profile Crate: } ``` -The JSON-LD Context entity: +An entity representing a JSON-LD context: * MUST have an `encodingFormat` of `application/ld+json` * MUST have an absolute URI as `@id`, which MUST be retrievable as JSON-LD directly or with content-negotiation and/or HTTP redirects. @@ -568,14 +569,17 @@ The JSON-LD Context entity: * SHOULD have a descriptive [name] * SHOULD have a `conformsTo` to the contextual entity `http://www.w3.org/ns/json-ld#Context` * MAY declare [version] according to [Semantic Versioning][semver] -- Updates MAY add new terms or patch fixes (with corresponding `version` change) +* Including the `DefinedTerm` for JSON-LD is optional. + +When updating a JSON-LD context in a Profile Crate: + +* Updates MAY add new terms or patch fixes (with corresponding `version` change in the RO-Crate metadata) * Updates SHOULD NOT remove terms already published and potentially used by consumers of the profile * Updates SHOULD NOT replace URIs terms map to -- except for typos. -* Including the `DefinedTerm` for JSON-LD is optional. Note that the referenced context URI does _not_ have to match the `@context` of the Profile Crate itself. -{% include callout.html type="tip" content="The `@context` MAY be the Profile Crate's Metadata JSON-LD file itself if +{% include callout.html type="tip" content="The `@context` MAY be the Profile Crate's Metadata JSON-LD file itself, if it is [resolvable](appendix/jsonld#ro-crate-json-ld-media-type) as media type `application/ld+json` over HTTP. Make sure the crate includes the defined terms both within its `@context` and ideally as entities in its `@graph`." %} @@ -583,11 +587,11 @@ defined terms both within its `@context` and ideally as entities in its `@graph` #### Multiple profiles -RO-Crate profiles sometimes build on each other. Note that unlike traditional object-oriented programming with strict class hierarchies, profiles are a looser construct of conventions rather than absolute rules. RO-Crate therefore do not enforce any particular "inheritance" across profiles. +RO-Crate profiles sometimes build on each other. Note that unlike traditional object-oriented programming with strict class hierarchies, profiles are a looser construct of conventions rather than absolute rules. RO-Crate therefore does not enforce any particular "inheritance" across profiles. -A crate conforming to multiple RO-Crate profiles SHOULD explicitly declare `conformsTo` for each profile. Each profile MUST have a corresponding contextual entity for each. +An RO-Crate conforming to multiple RO-Crate profiles SHOULD explicitly declare `conformsTo` for each profile. Each profile listed MUST have a corresponding contextual entity. -A Profile Crate can _suggest_ interoperable profiles under `hasPart`, and recommend them by using the role `http://purl.org/dc/terms/conformsTo` in a resource descriptor. For example, the specializing [Workflow Run Crate profile](https://w3id.org/ro/wfrun/workflow/0.4) recommends two other profiles, the "parent" Process Run Crate and a "mix-in" Workflow RO-Crate: +A Profile Crate can _suggest_ interoperable profiles under `hasPart`, and recommend them by using the role `http://purl.org/dc/terms/conformsTo` in a resource descriptor. For example, the [Workflow Run Crate profile](https://w3id.org/ro/wfrun/workflow/0.4) recommends two other profiles, the "parent" Process Run Crate and a "mix-in" Workflow RO-Crate: ```json { diff --git a/docs/_specification/1.2-DRAFT/provenance.md b/docs/_specification/1.2-DRAFT/provenance.md index b3633953..4118613e 100644 --- a/docs/_specification/1.2-DRAFT/provenance.md +++ b/docs/_specification/1.2-DRAFT/provenance.md @@ -34,7 +34,7 @@ parent: RO-Crate 1.2-DRAFT ## Equipment used to create files -To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Context Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number, manufacturer that identifies it as completely as possible. In this case the equipment is a bespoke machine. The equipment SHOULD be described on a web page, and the address of the description SHOULD be used as its `@id`. +To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Contextual Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number and manufacturer that identify the equipment as completely as possible. In the following case the equipment is a bespoke machine. The equipment SHOULD be described on a web page, and the address of the description SHOULD be used as its `@id`. ```json @@ -48,39 +48,39 @@ To specify which **equipment** was used to create or update a [Data Entity](data ``` -Uses [CreateAction] and [UpdateAction] type to model the contributions of _Context Entities_ of type [Person] or [Organization] in the creation of files. +Use the [CreateAction] and [UpdateAction] types to model the contributions of _Contextual Entities_ of type [Person] or [Organization] in the creation of files. -In this example the CreateAction has a human [agent], the object is a Place (a cave) and the Hovermap drone is the [instrument] used in the file creation event. +In the example below, the [CreateAction] has a human [agent], the [object] is a [Place] (a cave) and the Hovermap drone is the [instrument] used in the file creation event. ```json { - "@id": "#DataCapture_wcc02", - "@type": "CreateAction", - "agent": { - "@id": "https://orcid.org/0000-0002-1672-552X" - }, - "instrument": { - "@id": "https://confluence.csiro.au/display/ASL/Hovermap" - }, - "object": { - "@id": "#victoria_arch" - }, - "result": [ - { - "@id": "wcc02_arch.laz" - }, - { - "@id": "wcc02_arch_traj.txt" - } - ] + "@id": "#DataCapture_wcc02", + "@type": "CreateAction", + "agent": { + "@id": "https://orcid.org/0000-0002-1672-552X" + }, + "instrument": { + "@id": "https://confluence.csiro.au/display/ASL/Hovermap" + }, + "object": { + "@id": "#victoria_arch" + }, + "result": [ + { + "@id": "wcc02_arch.laz" }, - { - "@id": "#victoria_arch", - "@type": "Place", - "address": "Wombeyan Caves, NSW 2580", - "name": "Victoria Arch" - } + { + "@id": "wcc02_arch_traj.txt" + } + ] +}, +{ + "@id": "#victoria_arch", + "@type": "Place", + "address": "Wombeyan Caves, NSW 2580", + "name": "Victoria Arch" +} ``` @@ -108,41 +108,41 @@ In the below example, an image with the `@id` of `pics/2017-06-11%2012.56.14.jpg ```json { - "@id": "#Photo_Capture_1", - "@type": "CreateAction", - "agent": { - "@id": "https://orcid.org/0000-0002-3545-944X" - }, - "description": "Photo snapped on a photo walk on a misty day", - "endTime": "2017-06-11T12:56:14+10:00", - "instrument": [ - { - "@id": "#EPL1" - }, - { - "@id": "#Panny20mm" - } - ], - "result": { - "@id": "pics/2017-06-11%2012.56.14.jpg" - } - }, + "@id": "#Photo_Capture_1", + "@type": "CreateAction", + "agent": { + "@id": "https://orcid.org/0000-0002-3545-944X" + }, + "description": "Photo snapped on a photo walk on a misty day", + "endTime": "2017-06-11T12:56:14+10:00", + "instrument": [ { - "@id": "#SepiaConversion_1", - "@type": "CreateAction", - "name": "Convert dog image to sepia", - "description": "convert -sepia-tone 80% test_data/sample/pics/2017-06-11\\ 12.56.14.jpg test_data/sample/pics/sepia_fence.jpg", - "endTime": "2018-09-19T17:01:07+10:00", - "instrument": { - "@id": "https://www.imagemagick.org/" - }, - "object": { - "@id": "pics/2017-06-11%2012.56.14.jpg" - }, - "result": { - "@id": "pics/sepia_fence.jpg" - } + "@id": "#EPL1" }, + { + "@id": "#Panny20mm" + } + ], + "result": { + "@id": "pics/2017-06-11%2012.56.14.jpg" + } +}, +{ + "@id": "#Sepia_Conversion_1", + "@type": "CreateAction", + "name": "Convert dog image to sepia", + "description": "convert -sepia-tone 80% test_data/sample/pics/2017-06-11\\ 12.56.14.jpg test_data/sample/pics/sepia_fence.jpg", + "endTime": "2018-09-19T17:01:07+10:00", + "instrument": { + "@id": "https://www.imagemagick.org/" + }, + "object": { + "@id": "pics/2017-06-11%2012.56.14.jpg" + }, + "result": { + "@id": "pics/sepia_fence.jpg" + } +} ``` {% include callout.html type="tip" content="If representing command lines, double escape `\\` so that JSON preserves the `\` character." %} diff --git a/docs/_specification/1.2-DRAFT/structure.md b/docs/_specification/1.2-DRAFT/structure.md index 1e2ff6d8..a834e621 100644 --- a/docs/_specification/1.2-DRAFT/structure.md +++ b/docs/_specification/1.2-DRAFT/structure.md @@ -148,7 +148,7 @@ If present in the root directory of a _Attached RO-Crate_ as `ro-crate-preview.h * For keys that resolve in the `RO-Crate JSON-LD Context` to a URI, indicate this (the simplest way is to link the key to its definition). * If there are additional resources necessary to render the preview (e.g. CSS, JSON, HTML), link to them in a subdirectory `ro-crate-preview_files/` -The _RO-Crate Website_ is not considered a part of the RO-Crate, but serves as a way to make metadata available in a user-appropriate format. The `ro-crate-preview.html` file and the `ro-crate-preview_files/` directory and any contents SHOULD NOT be included in the `hasPart` property of the _Root Dataset_ or any other `Dataset` entity within an RO-Crate. +The _RO-Crate Website_ is not considered a part of the RO-Crate, but serves as a way to make metadata available in a user-appropriate format. The `ro-crate-preview.html` file and the `ro-crate-preview_files/` directory and any contents SHOULD NOT be included in the `hasPart` property of the _Root Data Entity_ or any other `Dataset` entity within an RO-Crate. Metadata about parts of the _RO-Crate Website_ MAY be included in an RO-Crate as in the following example. Metadata such as an `author` property, `dateCreated` or other provenance can be included, including details about the software that created them, as described in [Software used to create files](./provenance.html#software-used-to-create-files)). diff --git a/docs/_specification/1.2-DRAFT/workflows.md b/docs/_specification/1.2-DRAFT/workflows.md index 0664d748..84994080 100644 --- a/docs/_specification/1.2-DRAFT/workflows.md +++ b/docs/_specification/1.2-DRAFT/workflows.md @@ -94,7 +94,7 @@ Here are some indicators for when a script should be considered a _workflow_: Here are some counter-indicators for when a script might **not** be a workflow: * The script contains mainly algorithms or logic -* Data is exchanged out of bands, e.g. a SQL database +* Data is exchanged with services outside of the system, e.g. a SQL database * The script relies on a particular state of the system (e.g. appends existing files) * An interactive user interface that controls the actions @@ -163,14 +163,19 @@ The image file format SHOULD be indicated with [encodingFormat] using an IANA re { "@id": "workflow/workflow.svg", "@type": ["File", "ImageObject"], - "encodingFormat": ["image/svg+xml"], + "encodingFormat": ["image/svg+xml", {"@id": "https://www.nationalarchives.gov.uk/PRONOM/fmt/92"}], "name": "Diagram of RetroPath2.0 workflow", "about": {"@id": "workflow/workflow.knime"} }, - +, +{ + "@id": "https://www.nationalarchives.gov.uk/PRONOM/fmt/92", + "name": "Scalable Vector Graphics", + "@type": ["WebPage", "Standard"] +} ``` -A workflow diagram may still be provided even if there is no programmatic `SoftwareSourceCode` that can be executed (e.g. because the workflow was done by hand). In this case the sketch itself is a proxy for the workflow and SHOULD have an `about` property referring to the _RO-Crate dataset_ as a whole (assuming the RO-Crate represents the outcome of a single workflow), or to other [Data Entities](data-entities) otherwise: +A workflow diagram may still be provided even if there is no programmatic `SoftwareSourceCode` that can be executed (e.g. because the workflow was done by hand). In this case the sketch itself is a proxy for the workflow and SHOULD have an `about` property referring to the _Root Data Entity_ as a whole (assuming the RO-Crate represents the outcome of a single workflow), or to other [Data Entities](data-entities) otherwise: ```json { @@ -192,7 +197,7 @@ When complying with this profile, the workflow data entities MUST describe these properties and their related contextual entities: [name], [programmingLanguage], [creator], [dateCreated], [license], [sdPublisher], [url], [version]. -The [ComputationalWorkflow profile][ComputationalWorkflow profile 1.0] explains the above and list additional properties that a compliant [ComputationalWorkflow][ComputationalWorkflow 1.0] data entity SHOULD include: [citation], [contributor], [creativeWorkStatus], [description], [funding], [hasPart], [isBasedOn], [keywords], [maintainer], [producer], [publisher], [runtimePlatform], [softwareRequirements], [targetProduct] +The [ComputationalWorkflow profile][ComputationalWorkflow profile 1.0] explains the above and lists additional properties that a compliant [ComputationalWorkflow][ComputationalWorkflow 1.0] data entity SHOULD include: [citation], [contributor], [creativeWorkStatus], [description], [funding], [hasPart], [isBasedOn], [keywords], [maintainer], [producer], [publisher], [runtimePlatform], [softwareRequirements], [targetProduct] A data entity conforming to the [ComputationalWorkflow profile][ComputationalWorkflow profile 1.0] SHOULD declare the versioned profile URI using the [conformsTo] property [^18]: @@ -212,7 +217,7 @@ A data entity conforming to the [ComputationalWorkflow profile][ComputationalWor ### Describing inputs and outputs The input and output _parameters_ for a workflow or script can be given with `input` and `output` to [FormalParameter][FormalParameter 1.0] -contextual entities. Note that this entity usually represent a _potential_ input/output value in a reusable +contextual entities. Note that this entity type usually represents a _potential_ input/output value in a reusable workflow, much like [function parameter definitions] in general programming. If complying with the Bioschemas [FormalParameter profile][FormalParameter profile 1.0], @@ -232,7 +237,7 @@ A contextual entity conforming to the [FormalParameter profile][FormalParameter } ``` -{% include callout.html type="note" content="`input`, `output` and `FormalParameter` are at time of writing proposed by Bioschemas and not yet integrated in Schema.org" %} +{% include callout.html type="note" content="`input`, `output` and `FormalParameter` are at time of writing proposed by Bioschemas and not yet integrated in Schema.org." %} ## Complete Workflow Example